Persistence guide

Easy persistence over HTTP.

Create, read, update, delete, and list entities. Use JSON or EDN.

The whole API

Five operations cover the basics.

An entity has an id, a type, and any data you want to store.

POST /entities

Create

Store one entity.

POST /queries/find-entity-by-id

Read

Get one entity by id.

POST /entities/update

Update

Replace its type and data.

POST /entities/delete

Delete

Remove one entity.

POST /queries/find-entities-by-type

List

Page through one type.

Copy and run

The complete cURL flow

Set your URL and key once, then use the five requests below.

Set up

Use the production URL and your API key.

Example

export API_BASE_URL=https://shipdeploy.work/api/v1
export SHIP_DEPLOY_API_KEY=replace-with-your-api-key

1. Create

Store a note. Data can contain any JSON object.

Example

curl -X POST "$API_BASE_URL/entities.json" \
  -H 'content-type: application/json' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{"id":"note-1","type":"note","data":{"title":"First note","done":false}}'

2. Read

Fetch the entity by id.

Example

curl -X POST "$API_BASE_URL/queries/find-entity-by-id.json" \
  -H 'content-type: application/json' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{"id":"note-1"}'

3. Update

Replace the entity data for the same id.

Example

curl -X POST "$API_BASE_URL/entities/update.json" \
  -H 'content-type: application/json' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{"id":"note-1","type":"note","data":{"title":"First note","done":true}}'

4. List

List notes, newest first.

Example

curl -X POST "$API_BASE_URL/queries/find-entities-by-type.json" \
  -H 'content-type: application/json' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{"type":"note","page":1,"page-size":20,"sort-by":"updated-at","sort-direction":"desc"}'

5. Delete

Soft delete removes the entity from normal reads and lists.

Example

curl -X POST "$API_BASE_URL/entities/delete.json" \
  -H 'content-type: application/json' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{"id":"note-1","mode":"soft"}'

JSON or EDN

Choose per request.

Use .json with JSON or .edn with EDN. The same persistence operations support both formats.

Example

curl -X POST "$API_BASE_URL/entities.edn" \
  -H 'content-type: application/edn' \
  -H 'accept: application/edn' \
  -H "x-api-key: $SHIP_DEPLOY_API_KEY" \
  -d '{:id "note-2" :type "note" :data {:title "EDN note" :done false}}'

Ready to try it?

Create a temporary account and run the requests with a real key.

Create a demo account