Skip to main content

KVService API

Entrypoint

OnlineEnvironmentEntrypointHealthcheck
Staginghttps://kv-service.nextnext.idhttps://kv-service.nextnext.id/healthz
Productionhttps://kv-service.next.idhttps://kv-service.next.id/healthz

Structure

All requests and responses should be Content-Type: application/json.

About struct patching

We choose RFC 7396 standard for KV modifying.

Client should choose a lib which implements this.

e.g. json-merge-patch for JavaScript, json-patch for Rust.

Group KV

Get current KV of a avatar [GET /v1/kv]

  • Request (application/json)

    • Parameters

      • avatar (string, required) - Avatar public key (hexstring started with 0x).
    • Example

      GET /v1/kv?avatar=0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575

  • Response 200 (application/json)

    • Attributes (object)

      • avatar (string, required) - Avatar public key (uncompressed hexstring started with 0x).
      • proofs (array[object], required) - All proofs belong to this avatar
        • platform (string, required) - Platform (incl. nextid, which means public key itself).
        • identity (string, required) - Identity.
        • content (object, required) - KV-pair of this entry.
    • Body

      {
      "avatar": "0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575",
      "proofs": [{
      "platform": "nextid",
      "identity": "0x04c7cacde73.....",
      "content": {
      "this": "is",
      "a": ["sample", "kv", "content"]
      }
      }, {
      "platform": "twitter",
      "identity": "yeiwb",
      "content": {
      "twitter": "only",
      "kv": ["content", "goes", "here"]
      }
      }]
      }
  • Response 404 (application/json)

Persona not found (no KV was ever created).

Get signature payload for updating [POST /v1/kv/payload]

Make sure to save order-aware struct in [] value.

  • Request (application/json)

    • Attributes (object)

      • avatar (string, required) - Avatar public key (both comressed / uncompressed and with/without 0x are OK).
      • platform (string, required) - Platform (incl. nextid, which means public key itself).
      • identity (string, required) - Identity.
      • patch (object, required) - Patch to current data
    • Body

      {
      "avatar": "0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575",
      "platform": "nextid",
      "identity": "0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575",
      "patch": {
      "this": "is",
      "a": "sample",
      "structure": ["it", "could", "be", "anything"],
      "key": {
      "to": {
      "delete": null
      }
      }
      }
      }
  • Response 200 (application/json)

    • Attributes (body)

      • uuid (string, required) - UUID for this patch action. Send this UUID in POST /v1/kv as-is.
      • created_at (number, required) - Creation timestamp of this request. Send this in POST /v1/kv as-is.
      • sign_payload (string, required) - String to sign to.
    • Body

      {
      "uuid": "40c13c92-31e5-40d1-aebb-143d8e5b9c5e",
      "created_at": 1646983606,
      "sign_payload": "{\"action\":\"kv\",\"created_at\":1646983606,\"patch\":{\"a\":\"sample\",\"key_to_delete\":null,\"structure\":[\"it\",\"could\",\"be\",\"anything\"],\"this\":\"is\"},\"prev\":null,\"uuid\":\"40c13c92-31e5-40d1-aebb-143d8e5b9c5e\"}"
      }

Apply a patch [POST /v1/kv]

  • Request (application/json)

    • Attributes (object)

      • avatar (string, required) - Avatar public key (hexstring, both comressed / uncompressed are OK).
      • platform (string, required) - Platform (incl. nextid, which means public key itself).
      • identity (string, required) - Identity.
      • uuid (string, required) - UUID given by POST /v1/kv/payload.
      • created_at (number, required) - Creation timestamp given by POST /v1/kv/payload.
      • signature (string, required) - Signature of this request. Base64-ed.
      • patch (object, required) - Patch content
    • Body

      {
      "avatar": "0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575",
      "platform": "nextid",
      "identity": "0x04c7cacde73af939c35d527b34e0556ea84bab27e6c0ed7c6c59be70f6d2db59c206b23529977117dc8a5d61fa848f94950422b79d1c142bcf623862e49f9e6575",
      "uuid": "40c13c92-31e5-40d1-aebb-143d8e5b9c5e",
      "created_at": 1646983606,
      "signature": "BASE64_SIGNATURE_HERE",
      "patch": {
      "this": "is",
      "a": "sample",
      "structure": ["it", "could", "be", "any", "JSON"],
      "key": {
      "to": {
      "delete": null
      }
      }
      }
      }
  • Response 201 (application/json)

Created successfully. Response is same as GET /v1/kv.