Database REST API
A standard deployed Codehooks.io application has a complete and secure REST API for basic database CRUD operations. The CRUD REST API is implemented by bundling the deployed application with the Crudlify package.
All database URL endpoints are prefixed with the project ID, Codehooks api endpoint, and the database space name. For example, if your project ID is myproject
and the database space is dev
, then the full URL endpoint for the REST API is: https://myproject-ff00.api.codehooks.io/dev/people?name=Ally
.
Create and manage collections with the Codehooks CLI command coho createcollection
or using the Codehooks Studio [➕ Create collection] menu.
All databases are protected with encrypted HTTPS protocol, secure API tokens or JWT tokens. You can also add IP filters and much more, read more about Authentication here.
List your database API tokens with the CLI command coho info
. Create new API tokens with the CLI command coho add-token
.
Database REST API quick overview
API description | HTTP verb | Route |
---|---|---|
Get list of documents | GET | /:collection |
Get documents by query | GET | /:collection?query |
Get document by ID | GET | /:collection/:ID |
Create a new document | POST | /:collection |
Update a document by ID | PATCH | /:collection/:ID |
Replace a document by ID | PUT | /:collection/:ID |
Delete a document by ID | DELETE | /:collection/:ID |
Update multiple documents by query | PATCH | /:collection/:ID/_byquery |
Delete multiple documents by query | DELETE | /:collection/:ID/_byquery |
Get list of documents
Retrieve all collection data.
URL: /:collection[?options]
Method: GET
Parameters:
- collection: a valid collection name, e.g.
people
Options:
- limit: limit result, e.g.
?limit=2
- offset: skip forward in data result set
- fields: comma separated list of fields to show, e.g.
?limit=2&fields=Last Name,Sex
- sort: comma separated list of fields to sort result by, e.g.
?limit=2&sort=-Sex,Last Name
Returns Array of JSON documents
Code example
curl 'https://myproject-ff00.api.codehooks.io/dev/people?limit=2' \
-H 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
[
{
"Index": 54901,
"User Id": "d088FCEC6EDEF20",
"First Name": "Michaela",
"Last Name": "Callahan",
"Sex": "Male",
"Email": "[email protected]",
"Phone": "108-950-4850x6836",
"Date of birth": "2010-11-07",
"Job Title": "Research scientist (maths)",
"_id": "64bb88b51ed9a3057ac99d9c"
},
{
"Index": 54902,
"User Id": "40Fd72E5AaC5b67",
"First Name": "Lacey",
"Last Name": "Saunders",
"Sex": "Male",
"Email": "[email protected]",
"Phone": "623.506.2528x932",
"Date of birth": "1946-06-28",
"Job Title": "Insurance claims handler",
"_id": "64bb88b51ed9a3057ac99d9d"
}
]
Error response 401 no access
401 no access
Get documents by query
Retrieve collection data filtered by a query parameter.
URL: /:collection[?query&options]
Method: GET
Parameters:
- collection: a valid collection name, e.g.
people
Query:
- name=value: simple queries using URL parameters, e.g.
?First Name=Michaela
- q: advanced MongoDB query, e.g.
?q={"First Name": {"$regex": "en"}, "Last Name": {"$in": ["Saunders", "Massey"]}}
Options:
- limit: limit result, e.g.
?limit=2
- offset: skip forward in data result set
- fields: comma separated list of fields to show, e.g.
?limit=2&fields=Last Name,Sex
- sort: comma separated list of fields to sort result by, e.g.
?limit=2&sort=-Sex,Last Name
Returns Array of JSON documents
Code example: simple query
curl --location 'https://myproject-ff00.api.codehooks.io/dev/people?First%20Name=Michaela&fields=First%20Name%2CEmail%2C_id' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
[
{
"First Name": "Michaela",
"Email": "[email protected]",
"_id": "64bb88b51ed9a3057ac99d9c"
}
]
Code example: advanced query
Notice that advanced query parameter q={...}
should be programmatically URL encoded before sent to the server.
E.g. the query:
{"First Name":{"$regex":"en"},"Last Name":{"$in":["Saunders","Massey"]}}
when URL encoded equals:
{%22First%20Name%22%3A{%22%24regex%22%3A%22en%22}%2C%22Last%20Name%22%3A{%22%24in%22%3A[%22Saunders%22%2C%22Massey%22]}}
curl --location --globoff 'http://alf1-o5gi.api.codehooks.local.io/dev/people?q={%22First%20Name%22%3A{%22%24regex%22%3A%22en%22}%2C%22Last%20Name%22%3A{%22%24in%22%3A[%22Saunders%22%2C%22Massey%22]}}' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
[
{
"Index": 54907,
"User Id": "18E57F5a6aaC1ab",
"First Name": "Darlene",
"Last Name": "Saunders",
"Sex": "Female",
"Email": "[email protected]",
"Phone": "001-158-700-3226",
"Date of birth": "1970-08-23",
"Job Title": "Scientist, forensic",
"_id": "64bb88b51ed9a3057ac99da2"
},
{
"Index": 54933,
"User Id": "aeD915eA429Fb02",
"First Name": "Lauren",
"Last Name": "Massey",
"Sex": "Male",
"Email": "[email protected]",
"Phone": "+1-716-581-5746x2442",
"Date of birth": "2001-10-21",
"Job Title": "Information systems manager",
"_id": "64bb88b51ed9a3057ac99dbc"
}
]
Error response 401 no access
401 no access
Error response 400 Bad Request
Unexpected token } in JSON at position 5
Get document by ID
Retrieve a document from a collection.
URL: /:collection/:ID
Method: GET
Parameters:
- collection: a valid collection name, e.g.
people
- ID: an existing document
_id
value
Returns A JSON document
Code example
curl --location 'https://myproject-ff00.api.codehooks.io/dev/people/64bb88b51ed9a3057ac99d9c' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
{
"Index": 54901,
"User Id": "d088FCEC6EDEF20",
"First Name": "Michaela",
"Last Name": "Callahan",
"Sex": "Male",
"Email": "[email protected]",
"Phone": "108-950-4850x6836",
"Date of birth": "2010-11-07",
"Job Title": "Research scientist (maths)",
"_id": "64bb88b51ed9a3057ac99d9c"
}
Error response 401 no access
401 no access
Error response 404 Not Found
3 INVALID_ARGUMENT: NotFoundError: Key not found in database [64bb88b51ed9a3057ac99d9cc]
Create a new document
Insert a new JSON document in a collection.
URL: /:collection
Method: POST
Parameters:
- collection: a valid collection name, e.g.
people
- body: a valid JSON document
Returns The created JSON document
Code example
curl --location 'https://myproject-ff00.api.codehooks.io/dev/people' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149' \
--header 'Content-Type: application/json' \
--data-raw '{
"First Name": "Jim",
"Last Name": "Callahan",
"Email": "[email protected]",
"Phone": "108-950-4850x6836",
"Date of birth": "1995-11-07",
"Job Title": "Software tester"
}'
Success response 201 Created
{
"First Name": "Jim",
"Last Name": "Callahan",
"Email": "[email protected]",
"Phone": "108-950-4850x6836",
"Date of birth": "1995-11-07",
"Job Title": "Software tester",
"_id": "64bbc861f13609074a5d981a"
}
Error response 401 no access
401 no access
Error response 400 Bad Request
SyntaxError: Unexpected token S in JSON at position 174
Update a document by ID
Update a JSON document in a collection.
URL: /:collection/:ID
Method: PATCH
Parameters:
- collection: a valid collection name, e.g.
people
- ID: a valid document
_id
- body: a valid JSON document
Returns The updated JSON document
Code example
curl --location --request PATCH 'https://myproject-ff00.api.codehooks.io/dev/people/64bbc861f13609074a5d981a' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149' \
--header 'Content-Type: application/json' \
--data '{
"Phone": "123-345-12332x6836",
"Job Title": "Bug master"
}'
Success response 200 OK
{
"First Name": "Jim",
"Last Name": "Callahan",
"Email": "[email protected]",
"Phone": "123-345-12332x6836",
"Date of birth": "1995-11-07",
"Job Title": "Bug master",
"_id": "64bbc861f13609074a5d981a"
}
Error response 401 no access
401 no access
Error response 400 Bad Request
E.g. invalid JSON document.
Bad request
Replace a document by ID
Replace a JSON document in a collection.
URL: /:collection/:ID
Method: PUT
Parameters:
- collection: a valid collection name, e.g.
people
- ID: a valid document
_id
- body: a valid JSON document
Returns The replaced JSON document
Code example
curl --location --request PUT 'https://myproject-ff00.api.codehooks.io/dev/people/64bbc861f13609074a5d981a' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149' \
--header 'Content-Type: application/json' \
--data '{
"First Name": "Re",
"Last Name": "Placed",
"Job Title": "Replacer"
}'
Success response 200 OK
{
"First Name": "Re",
"Last Name": "Placed",
"Job Title": "Replacer",
"_id": "64bbc861f13609074a5d981a"
}
Error response 401 no access
401 no access
Error response 400 Bad Request
E.g. invalid JSON document.
Bad request
Delete a document by ID
Delete a JSON document in a collection.
URL: /:collection/:ID
Method: DELETE
Parameters:
- collection: a valid collection name, e.g.
people
- ID: a valid document
_id
Returns The deleted document _id
Code example
curl --location --request DELETE 'https://myproject-ff00.api.codehooks.io/dev/people/64bbc861f13609074a5d981a' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
{
"_id": "64bbc861f13609074a5d981a"
}
Error response 401 no access
401 no access
Update multiple documents by query
Update multiple JSON document by query in a collection.
URL: /:collection/_byquery[?query&options]
Method: PATCH
Parameters:
- collection: a valid collection name, e.g.
people
- body: a valid JSON document to update on all matches
Query:
- name=value: simple queries using URL parameters, e.g.
?Job Title="Scientist, forensic"
- q: advanced MongoDB query, e.g.
?q={"First Name": {"$regex": "en"}, "Last Name": {"$in": ["Saunders", "Massey"]}}
Returns Count of updated documents
Code example
curl --location --request PATCH 'https://myproject-ff00.api.codehooks.io/dev/people/_byquery?Job%20Title=%22Scientist%2C%20forensic%22' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149' \
--header 'Content-Type: application/json' \
--data '{
"$set": {
"salary": "high"
},
"$inc": {
"visited": 1
}
}'
Success response 200 OK
{
"count": 2
}
Error response 401 no access
401 no access
Error response 400 Bad Request
Bad Request
Delete multiple documents by query
Delete multiple JSON document by query in a collection.
Please ensure that the applied query is correct. An empty query parameter will erase all documents in collection.
URL: /:collection/_byquery[?query&options]
Method: DELETE
Parameters:
- collection: a valid collection name, e.g.
people
Query:
- name=value: simple queries using URL parameters, e.g.
?Job Title="Scientist, forensic"
- q: advanced MongoDB query, e.g.
?q={"First Name": {"$regex": "en"}, "Last Name": {"$in": ["Saunders", "Massey"]}}
Returns Count of deleted documents
Code example
curl --location --request DELETE 'http://myproject-ff00.api.codehooks.io/dev/people/_byquery?Job%20Title=%22Scientist%2C%20forensic%22' \
--header 'x-apikey: 3c932310-3fab-4ba3-8102-b75ba0f05149'
Success response 200 OK
{
"count": 2
}
Error response 401 no access
401 no access