Object upsert

Create new objects. If an object already exists, update its definition. Returns performed action. In case of configured delivery, the action is notified to the listener.

POST
{{host}}/v1/object?object={{object name}}
VERB:POST
BASE URL:{{host}}/v1/object
QUERY STRING:?object={{object name}}

Query parameters#

  • objectstring
    Required

    Unique name of the object in the URL.

    format:
    abc:0-9@owner

Headers#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-api-keyRequired

    Your BigState API key.

    *provide api key here*
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

See authentication headers here.

Request body#

  • Typical payload
    {

      "type": 2,

      "ttl": 100000,

      "validity": 60,

      "versionDeep": 20,

      "info": {

        "name": "{{owner1}} position",

        "desc": "Contains information about user position",

        "example": {

          "lng": 53.11,

          "lat": 53.11

        }

      }

    }
  • Partial (all fields except info)
    {

      "type": 2,

      "ttl": 100000,

      "validity": 60,

      "versionDeep": 20

    }
  • Minimal (type field only)
    {}

Request parameters#

  • typenumber
    Optional

    How values for this object are encoded on the wire.

    Values

    • 2 — JSON object
    • 3 — number
    • 4 — string
    • 5 — Base64 binary data
    default:
    2
  • ttlnumber
    Optional

    Time to live in seconds: lifetime of the object itself and all related data such as state.

    minValue:
    0
  • validitynumber
    Optional

    Duration of validity of state in seconds. The state can still be recovered afterward but is no longer considered useful or valid.

    example: Truck position valid for 10 minutes — use 600
    default:
    Not applied (no limit)
  • versionDeepnumber
    Optional

    Number of past version states kept in history.

    default:
    0 (no history stored)
  • infoobject
    Optional

    Metadata that helps readers understand what the object is used for.

    • info.namestring
      Optional

      Human-readable name of the object.

    • info.descstring
      Optional

      Description of the object.

    • info.exampleany
      Optional

      Example of a typical value stored for this object.

Response parameters#

  • 200Response body · object

    Object successfully created or updated.

    {

      "action": 1

    }
    • actionnumber

      Indicates which operation was performed.

      Values

      • 1 — created
      • 2 — updated
  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 400Response body · object

    Bad request.

    {

      "error": 6,

      "desc": "\"Object must be formatted as object"

    }
    • errornumber

      Numeric error code. See the error codes reference for the full list.

    • descstring

      Human-readable description of the error.

Examples#

Upsert object

An object about a person’s position—a field worker, a fleet truck, anything that moves: the body includes `info` with a display name, a short blurb, and a sample map point (lng/lat). Use it when you want not just a resource in the API, but a clear story of what this coordinate stream is and how it reads for humans.

curl 'https://api.bigstate.dev/v1/object?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \

  --request POST \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json' \

  --data '{

  "type": 2,

  "ttl": 100000,

  "validity": 60,

  "versionDeep": 20,

  "info": {

    "name": "{{owner1}} position",

    "desc": "Contains information about user position",

    "example": {

      "lng": 53.11,

      "lat": 53.11

    }

  }

}'

Upsert object (minimal payload)

Same “something with a position” idea, but without the narrative in `info`: only type, TTL, and validity—like a stub you’ll flesh out later, or when human-readable labels and a sample coordinate can wait. The resource name still lives in the query string; you don’t have to carry all the metadata in the first request.

curl 'https://api.bigstate.dev/v1/object?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition1%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \

  --request POST \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json' \

  --data '{

  "type": 2,

  "ttl": 100000,

  "validity": 60,

  "versionDeep": 20

}'
MatchGet

© 2024 BigState