Database REST API

One of the core features of the restdb.io database cloud service is the Restful API which automatically reflects your database schema. All restdb.io databases have a unique URL as a REST endpoint. Client applications communicate through the URL with JSON objects.

🚀 If you love the API and coding-parts of restdb.io, please also check out our new backend service: codehooks.io. It integrates Javascript serverless functions with a document database, a key/value database, a message queue and a CRON-like job system. A powerful CLI lets you instantly deploy new code.

Collection REST API

A database collection (same as a SQL table) contains your JSON documents.

HTTP VerbResource
GEThttps://<dburl>.restdb.io/rest/<collection>
↪Get list of JSON documents from database collection.
GEThttps://<dburl>.restdb.io/rest/<collection>/ID
Get one document from a collection. ID must be a valid ObjectID.
GEThttps://<dburl>.restdb.io/rest/<collection>/ID/<subcollection>
Get list of documents from subcollection (subcollection is field name of type child).
GEThttps://<dburl>.restdb.io/rest/<collection>/ID/<subcollection>/ID
Get document from subcollection (subcollection is field name of type child) and ID is a valid ObjectID.
POSThttps://<dburl>.restdb.io/rest/<collection>
Create a new document in a collection. Request body is a valid JSON document.
POSThttps://<dburl>.restdb.io/rest/<collection>/ID/<subcollection>
Create a child document in a sub collection.
POST arrayhttps://<dburl>.restdb.io/rest/<collection>
Post array data. Request body is an array of JSON documents. Optional parameter validate=false, for bulk inserts without validation. Will also work for child documents.
PUThttps://<dburl>.restdb.io/rest/<collection>/ID
Update a document in a collection. Request body is a valid JSON document.
PATCHhttps://<dburl>.restdb.io/rest/<collection>/ID
Update one or more properties on a document in a collection. Request body is a valid JSON object.
DELETEhttps://<dburl>.restdb.io/rest/<collection>/ID
Delete a document in a collection.
DELETE arrayhttps://<dburl>.restdb.io/rest/<collection>/*
Delete an array of documents in a collection. Request body must be an array of ID's.
DELETE queryhttps://<dburl>.restdb.io/rest/<collection>/*?q={...}
Delete a list of documents in a collection. List is based on query in parameter ?q={...}. Only allowed with a full access api-key or from a Codehook.

HTTPS is required. The restdb.io database REST API only responds to encrypted traffic so that your data remains safe. All API traffic must have a valid apikey or authorization JWT token as a parameter or as a request header field.

Read more about how to query database here.

Code examples for popular programming languages here.

Using POST to emulate PUT, DELETE, PATCH

If your development platform or firewall rules prevent you from calling HTTP methods like PUT, PATCH or DELETE, use the X-HTTP-Method-Override header. Pass the method you want to use in the X-HTTP-Method-Override header and make your call using the POST method.

Media Content API

Http VerbResource
GEThttps://<dburl>.restdb.io/media/ID
Get binary data for media object with ID. ID is a valid ObjectID for an object in the media archive or an existing filename. Parameter s options; ?s=t (thumbnail), ?s=w (web) and ?s=o (original size). No API-key required. Use parameter ?download=true if you want the image or file to be downloaded instead of displayed.
GEThttps://<dburl>.restdb.io/media/ID/meta
Get all JSON media object metadata. Requires API-key.
GEThttps://<dburl>.restdb.io/media/ID/meta/*[?q={}&h={}]
Query JSON media object metadata. E.g. https://<dburl>.restdb.io/media/*/meta?q={"filesize": {"$gt": 30000}}&h={"$max":10, "$orderby":{"filesize":-1}, "$fields": {"origname": 1, "filesize": 1, "_id": 1}}. Requires API-key.
GEThttps://<dburl>.restdb.io/media/*/meta?ids=ID1,ID2,...
Get list of JSON media object metadata. Requires API-key.
POSThttps://<dburl>.restdb.io/media
Post file(s) using the multipart/formdata protocol, view example. Requires API-key.
PUThttps://<dburl>.restdb.io/media
Not yet implemented
DELETEhttps://<dburl>.restdb.io/media/ID
Delete media content with ID. Requires API-key.

Read more about media archive here.

Meta Data API

Http VerbResource
GEThttps://<dburl>.restdb.io/rest/_meta
Get meta data for the database as a JSON object.
GEThttps://<dburl>.restdb.io/rest/<collection>/_meta
Get meta data for the collection as a JSON object.

Mail API

Http VerbResource
POSThttps://<dburl>.restdb.io/mail
Send email. Request body contains one document:
{"to": "...", "subject": "...", "html": "...", "company": "...", "sendername": "..."}
, or an array of documents [{…},{…}]

Read more about mail API here.

Authentication API

Http VerbResourceFunctionality
POSThttps://<database>/auth/jwtGenerate a new JWT token. Body must contain a path to a secret and a payload with JWT claims, e.g {"secret": "path from global settings", "payload": {"email": "xxx@example.com"}}
GEThttps://<database>/auth/userinfoGet data about a user. Returns email, displayname and image.
POSThttps://<database>/auth/logoutLogout a user, invalidates the login token. This token can no longer be used for API access.

Quick example

For our test database, the REST endpoint URL is:

https://rdb-simpledb.restdb.io/rest

GET - read all items from a collection with rest api

    curl -i -H "Accept: application/json"\
     -H "Content-Type: application/json"\
     -H "x-apikey: 560bd47058e7ab1b2648f4e7"\
     -X GET "https://rdb-simpledb.restdb.io/rest/product"

Run in Postman

Example database output from GET Restful request above:

    [
        {
            "_id": "5602647c7f98025500000041",
            "description": "Saepe adipisci illo restful dignissimos. Dicta generate occaecati ex ducimus.",
            "name": "Quaerat consectetur",
            "photos": [
                "55a68f6fc53a0b2a00000006"
            ],
            "serialno": "16177"
        },
        {
            "_id": "5602647c7f9802550000003c",
            "description": "Harum voluptas vitae restful consequatur with rest api.",
            "name": "Ratione iste recusandae",
            "photos": [
                "55a68f6fc53a0bbc00000009"
            ],
            "serialno": "23588"
        }
    ]

GET - read one database item from a collection requires an unique objectID (the _id field)

    curl -i -H "Accept: application/json"\
     -H "Content-Type: application/json"\
     -H "x-apikey: 560bd47058e7ab1b2648f4e7"\
     -X GET 'https://rdb-simpledb.restdb.io/rest/product/5602647c7f98025500000041'

Run in Postman