Create or update an object

An object is a named resource whose definition describes the state it accepts. An object can represent a device, user location, counter, or any other stateful entity, including type, retention, and version-history settings.

Create an object definition or replace the definition of an existing object with the same name. The definition controls the accepted state type, retention settings, version history, and descriptive metadata.

The response identifies whether the operation created or updated the object. If a matching delivery is configured, subscribers receive the corresponding object action.

Use Get an object to inspect the current definition before replacing it. After defining the object, write its first value with Set object state.

An update replaces the definition

Review the complete definition before submitting it.

Use the get endpoint to compare the current definition with the replacement payload.

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

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.

    {{apiKey}}
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

Need a session token? See Token sign in.

Request body#

  • Typical payload
    {

      "type": 2,

      "ttl": 100000,

      "validity": 60,

      "versionDeep": 20,

      "info": {

        "name": "{{owner}} 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)
    {

      "type": 2

    }

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. Use the response `desc` field for the human-readable explanation.

    • descstring

      Human-readable description of the error.

Examples#

Create or update an object

Create or replace an object definition with type, lifecycle settings, version retention, and optional descriptive metadata.

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": "{{owner}} position",

    "desc": "Contains information about the user’s position.",

    "example": {

      "lng": 53.11,

      "lat": 53.11

    }

  }

}'

Create or update an object (minimal payload)

Create or replace an object definition with type, lifecycle settings, and version retention.

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

}'
ObjectsGet

© 2024 BigState