LearnReferenceBlog
Protocol

POST new_record

Create a new record, or a new version of an existing record.

POST https://baq.run/api/alice/records

Properties to create a new record

  • id RecordId optional

    • Unique identifier of the record.

    • Defaults to a new random ID if missing.

  • created_at RecordDate optional

    • Creation date of the record.

    • Defaults to the current date if missing.

  • permissions RecordPermissions optional

  • type VersionLink

  • content object

    • Type-dependent content of the record.

Properties to update an existing record

  • author EntityLink optional

    • Author of the record to update.

    • Defaults to the user if missing.

  • id RecordId

    • Unique identifier of the record to update.

  • version object

    • Version-specific properties:

      • parent_hash VersionHash

        • Hash of the record version to update.

      • created_at RecordDate optional

        • Creation date of the record version.

        • Defaults to the current date if missing.

  • permissions RecordPermissions optional

    • Updated permissions for the record, if different.

  • type VersionLink optional

    • Updated link to the record schema, if different.

  • content object

    • Updated record content.

Properties to delete a record

  • author EntityLink optional

    • Author of the record to delete.

    • Defaults to the user if missing.

  • id RecordId

    • Unique identifier of the record to delete.

  • version object

    • Version-specific properties:

      • parent_hash VersionHash

        • Hash of the record version to delete.

      • created_at RecordDate optional

        • Creation date of the record version.

        • Defaults to the current date if missing.

  • no_content object optional

    • Deletion options:

      • action enum optional

        • Type of deletion to perform:

          • delete: Standard deletion, propagated to others.

          • local: Only delete from the user’s server, not propagated.

          • leave: Remove our user without deleting for others.

        • Defaults to delete if missing.

Headers

  • X-Baq-Credentials: ... optional

    • Properties:

      • algorithm="..." enum : Signature algorithm.

      • public_key="..." string : Base64 encoded public key.

    • Only include in the request when creating a new App­ or Relationship­ record.

Parameters

  • include_links string[] optional

    • Paths of links to include in the response (comma-separated).

    • Supports the following special values:

      • entity: Entity records for all entity links.

      • existential: All records for existential record links.

    • Defaults to entity,existential.

Notes

  • This endpoint is idempotent if the following properties are provided:

    • id

    • created_at / version.created_at

  • All links in a new record will be validated and must point to existing and accessible entities, records, and blobs.

  • This endpoint is atomic and the record is guaranteed to be visible in all other queries after the request completes.

Content

  • record Record

    • Newly created record.

  • linked_records Record[]

    • Linked records requested with include_links.

Headers

  • X-Baq-Credentials: ... optional

    • Properties:

      • algorithm="..." enum : Signature algorithm.

      • public_key="..." string : Base64 encoded public key.

    • Only part of the response when creating a new App­ or Relationship­ record.

Creating a new record only requires a type and content. Here, we create a new Post record­ with a short text message, and we make it public for everyone to read.

POST /api/alice/records HTTP/2
Host: baq.run
Content-Type: application/json

{
  "type": {
    "entity": "types.baq.dev",
    "record_id": "6ee7f69a90154b849bac528daa942bcd",
    "version_hash": "93ca1149e00ab963ea4b29772769e20330c356bb4b6ae787d3af9168e81d1687"
  },
  "content": {
    "text": "Hi everyone!"
  },
  "permissions": {
    "read": "public"
  }
}

In the response, the server has assigned the record a random ID and set the current date where needed. A hash of the record was also generated to uniquely identify this version of it.

HTTP/2 200 OK
Content-Type: application/json

{
  "record": {
    "author": {
      "entity": "alice.baq.run"
    },
    "id": "867deccbe7ac4adca4efc07fbe08af87",
    "source": "self",
    "created_at": "2024-03-05T16:50:17.9080000Z",
    "received_at": "2024-03-05T16:50:20.4850000Z",
    "version": {
      "author": {
        "entity": "alice.baq.run"
      },
      "hash": "563bebcafec0aea26d88384564d721b3026b27a42263200f7aee09366763630d",
      "created_at": "2024-03-05T16:50:17.9080000Z",
      "received_at": "2024-03-05T16:50:20.4850000Z"
    },
    "permissions": {
      "read": "public"
    },
    "type": {
      "entity": "types.baq.dev",
      "record_id": "6ee7f69a90154b849bac528daa942bcd",
      "version_hash": "93ca1149e00ab963ea4b29772769e20330c356bb4b6ae787d3af9168e81d1687"
    },
    "content": {
      "text": "Hi everyone!"
    }
  },
  "linked_records": []
}

Specifying the id and created_at fields in the request makes it possible to replay it multiple times without creating multiple records. The server will always return the exact same response.

POST /api/alice/records HTTP/2
Host: baq.run
Content-Type: application/json

{
  "id": "4c093b447c834e3ba62bc69c7ca7069f",
  "created_at": "2024-03-05T16:50:17.9080000Z",
  "type": {
    "entity": "types.baq.dev",
    "record_id": "6ee7f69a90154b849bac528daa942bcd",
    "version_hash": "93ca1149e00ab963ea4b29772769e20330c356bb4b6ae787d3af9168e81d1687"
  },
  "content": {
    "text": "Hi everyone!"
  },
  "permissions": {
    "read": "public"
  }
}

To update a record authored by the user, we only need to specify the id of the record, the parent_hash of the version to update, and the updated content to use.

POST /api/alice/records HTTP/2
Host: baq.run
Content-Type: application/json

{
  "id": "4c093b447c834e3ba62bc69c7ca7069f",
  "version": {
    "parent_hash": "93ca1149e00ab963ea4b29772769e20330c356bb4b6ae787d3af9168e81d1687"
  },
  "content": {
    "text": "Bye everyone!"
  }
}

To delete a record, we omit the content property. A no_content object can be provided to specify the deletion behavior.

POST /api/alice/records HTTP/2
Host: baq.run
Content-Type: application/json

{
  "id": "4c093b447c834e3ba62bc69c7ca7069f",
  "version": {
    "parent_hash": "93ca1149e00ab963ea4b29772769e20330c356bb4b6ae787d3af9168e81d1687"
  },
  "no_content": {
    "action": "delete"
  }
}
© 2024 Quentez