REST-API

Each of your app users can make REST-API calls to interact with the database and the collections you defined. API requests need to be authorized by a valid JWT token in the request's Authorization header that identifies the bearer as a single user of your project. To identify a valid client or origin, the sb-app-id header is required. The sb-app-secret header is only required if the origin domain is not whitelisted in your project's settings.

The path to access the database API is:

https://<project>-api.selfbits.io/api/v1/db/m/<schemaId>

Your unique schemaId (= collectionId) is used as part of the endpoint path. That means that a collection with id todo is accessible via:

https://<project>-api.selfbits.io/api/v1/db/m/todo

Create object

If you want to create a new object, use an authorized POST request and attach the JSON object in the request body. The following image is a screenshot of our API explorer and shows the required and optional input parameters.

To upload a new todo object, you would send a request like this:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
-d '{ \
    "name": "Cocktails at 9pm",\
    "details": "Meet with Matt at Enchilada to celebrate his birthday",\
    "startTimestamp": 1483477200,\
    "endTimestamp": 1483486200,\
    "userId": "u12345",\
    "tags": ["party", "Matt", "Saturday"],\
    "customData": {\
        "location": "Enchiladas",\
        "notificationActive": true\
    }\
}' "https://<project>-api.selfbits.io/api/v1/db/m/todo"

If your POST is successful, you receive status code 200 with the new object:

{
    "_id": "23o4iuh2l3k4h2l",
    "name": "Cocktails at 9pm",
    "details": "Meet with Matt at Enchilada to celebrate his birthday",
    "startTimestamp": 1483477200,
    "endTimestamp": 1483486200,
    "userId": "u12345",
    "tags": ["party", "Matt", "Saturday"],
    "customData": {
        "location": "Enchiladas",
        "notificationActive": true
    },
    "__version": 0,
    "__createdAt": 1483477200,
    "__updatedAt": 1483477200,
    "__createdBy": "u11111"
}

Query objects

If you want to query objects in your collection, use an authorized GET request:

The optional parameters are:

  • pageSize: (Number) how many objects are returned in a paged result. Default: 20.
  • pageNumber: (Number) Which page do you want to return. Default: 1.
  • deep: (Boolean) Do you want to replace ids of referenced objects by the actual object. Default: false.
  • meta: (Boolean) Do you want to return meta information like timestamps and version. Default: false.
  • filter: (String [URL encoded JSON object]) The query that you want to execute. We use the the standard mongoDB query language: Visit https://docs.mongodb.com/manual/core/document/#query-filter-documents to find out more about operators and selectors. To fetch all todo objects with startTimestamp greater than 1483477000 and userId equal to "u12345" you can use the following filter:
{
    "startTimestamp": {
        "$gt" : 1483477000
    },
    "userId": "u12345"
}
  • sort: (String [URL encoded JSON object]) The sorting that you want to apply. Use the sorting key as key and -1 (descending sort) or 1 (ascending sort) as the value. To sort our todo objects with descending startTimestamp and ascending name, you would use:
{
    "startTimestamp": -1,
    "name": 1
}

The response will be a paginated result that looks like this:

{
    "docs": [
        {<Matching object 1>},{<Matching object 2>} ...
    ],
    "total": 622,
    "limit": 20,
    "page": 1,
    "pages": 32
}
  • docs: Page as an array of objects that match the query
  • total: Total number of objects that match the query
  • limit: Maximum number of objects per page
  • page: Current page number
  • pages: Total number of pages specific to the current query

Read object

If you want to access a specific object, just send a GET request and append the object's _id to the endpoint path.

  • deep: (Boolean) Do you want to replace ids of referenced objects by the actual object. Default: false.
  • meta: (Boolean) Do you want to return meta information like timestamps and version. Default: false.

Update object

If you want to update an existing object, just use a PUT request with appended _id path and send the updated object in the body.

Delete object

If you want to delete a specific object, just send a DELETE request and append the object's _id to the endpoint path.