Documentation

Learn how to create databases and use the REST API.

Visit the blog for in-depth articles and tutorials.

Join our FB group to interact with the restdb.io team and active users.


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.

Collection REST API

A database collection (same as a SQL table) contains your JSON documents. All JSON documents gets a unique _id.

Http VerbResourceFunctionality
GEThttps://<dburl>.restdb.io/rest/<collection>Get list of JSON documents from database collection
GEThttps://<dburl>.restdb.io/rest/<collection>/IDGet 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>/IDGet 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>/IDUpdate a document in a collection. Request body is a valid JSON document.
PATCHhttps://<dburl>.restdb.io/rest/<collection>/IDUpdate one or more properties on a document in a collection. Request body is a valid JSON object.
DELETEhttps://<dburl>.restdb.io/rest/<collection>/IDDelete 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.

Media Content API

Http VerbResourceFunctionality
GEThttps://<dburl>.restdb.io/media/IDGet 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/metaGet JSON structure with media object metadata. Requires API-key.
POSThttps://<dburl>.restdb.io/mediaPost file(s) using the multipart/formdata protocol, view example. Requires API-key.
PUThttps://<dburl>.restdb.io/mediaNot yet implemented
DELETEhttps://<dburl>.restdb.io/media/IDDelete media content with ID. Requires API-key

Read more about media archive here

Meta Data API

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

Mail API

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

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