Nimbu's APIs empower you to take full control of your site’s functionality. Use the APIs to interact with site elements, your site’s database content, cloud code apps, themes and more. The APIs also give you access to information about your site, its users, and more.
You can create or copy an API token from the backend (via "Apps "Site Access Tokens") http://zenjoy.it/11WQV).
This token provides authentication to the REST-API, via https://api.nimbu.io. You can give this token via the HTTP Header "Authorization" or via the query parameter "access_token" in the url: e.g. https://api.nimbu.io/sites?access_token=
Authorization: Bearer eyJhbGcasdf...aXczt18H6437W
| Verb | URL | Description |
|---|---|---|
GET |
https://api.nimbu.io/orders | overview of all orders |
GET |
https://api.nimbu.io/orders/:number:/ | request specific order, :number: is the order number or order ID |
| Verb | URL | Description |
|---|---|---|
GET |
https://api.nimbu.io/products | overview of all products |
GET |
https://api.nimbu.io/products/customizations | overview of product data model, including all select / multi-select ids |
GET |
https://api.nimbu.io/products/:product_id:/ | request specific product, :product_id: is the product-id, the SKU or the slug (word for url-friendly unique name) |
POST |
https://api.nimbu.io/products | create new product |
PUT / PATCH |
https://api.nimbu.io/products/:product_id:/ | customize specific product |
DELETE |
https://api.nimbu.io/products/:product_id:/ | remove specific product - if this product is used in an already made order this is not possible and the product can only be archived. |
| Verb | URL | Description |
|---|---|---|
GET |
https://api.nimbu.io/customers | overview of all customers |
GET |
https://api.nimbu.io/customers/:customer_id:/ | request specific customer, :customer_id: is the customer number, or the database id |
POST |
https://api.nimbu.io/customers | create new customer, important here are the "skip_activation" and "skip_welcome" parameters, which determine whether the activation-flow is skipped or not and whether a welcome email is sent to the new account, without activation. |
PUT/ PATCH |
https://api.nimbu.io/customers/:customer_id:/ | customize specific customer |
DELETE |
https://api.nimbu.io/customers/:customer_id:/ | delete specific customer - only possible when this customer has no orders in the system |
| Verb | URL | Description |
|---|---|---|
| POST | https://api.nimbu.io/customers/login | login with certain credentials, if invalid status 401 will be returned, if successful the data of this user will be given, together with an additional field: "session_token" returned. You can then use this session token to do other API calls when logged in with this user. This is given via the HTTP header "X-Nimbu-Session-Token". You can test if you are properly logged in via https://api.nimbu.io/customers/me. Required parameters: "username" and "password" |
| GET | https://api.nimbu.io/customers/me | Only for logged in users, so with the X-Nimbu-Session-Token header: gives user info for the used session token. |
| POST | https://api.nimbu.io/customers/password/reset | Rhis allows you to send an email to reset the password (via the front-end). Required parameters: "email" |
| Verb | URL | Description |
|---|---|---|
GET |
https://api.nimbu.io/channels | overview of all channels and defined fields |
GET |
https://api.nimbu.io/channels/:channel:/entries | overview of all items in a channel |
GET |
https://api.nimbu.io/channels/:channel:/entries/:entry_id | retrieving a specific item from a channel |
POST |
https://api.nimbu.io/channels/:channel:/entries | create new item |
PUT/PATCH |
https://api.nimbu.io/channels/:channel:/entries/:entry_id | customize specific item |
DELETE |
https://api.nimbu.io/channels/:channel:/entries/:entry_id | Delete specific item |
On all overview endpoints (up to very complex) queries are possible. These are provided by a combination of query parameters or via the "where" parameter, which accepts queries in a more SQL-like syntax. The format is always "parameter"="value". To the parameter name you can add extensions to impose conditions other than "equalTo":
param=value: param == valueparam.ne=value: param != valueparam.gt=value: param > valueparam.gte=value: param >= valueparam.lt=value: param < valueparam.lte=value: param <= valueparam.contains=value: param contains value somewhere (like the %LIKE% query of sql)param.in=value1,value2,value3: parameter is one of the values from [value1,value2,value3].param.exists=true/false: param has been entered or is empty.param.start=value: param starts with valueparam.end=value: param ends with valueparam.regex=value: param match the regular expression valueOn all overview urls you can retrieve the number of matching documents by adding /count to the url, e.g. https://api.nimbu.io/orders/count.
With the sort query parameter query results can be sorted. The syntax is sort sort sort=param for ascending by param, sort=-param for descending order. Multiple parameters can be combined: sort=param1,-param2,param3
With the resolve and resolve_depth parameter it can be determined whether references should already be filled in with all data or not (sometimes useful to limit the number of http-requests).
The API uses pagination to limit the amount of data returned per http frequency. These are determined via the "per_page" parameter and the "page". E.g. https://api.nimbu.io/customers?per_page=500 answers per 500 records and https://api.nimbu.io/customers?page=2 gives the 2nd page, if available. The pagination options are as usual with REST-APIs returned in the answer in the "Link" http header. When there is no pagination available it is not set. A nice description of this system can be found at https://developer.github.com/guides/traversing-with-pagination/.
Our API defaults to responding with JSON.
All times are returned in UTC, ISO-8601 format. This is also the preferred format for parameter values, although the API has been made to try to make good use of whatever you send in date or time-like notation. For fields with a reference, the database id is used to indicate the reference. For select or multi-select fields, the id of the item is also returned in addition to the text value.
The API works with JSON messages and also expects for updates in the body of the http-frequest correctly formatted JSON messages. You can request a "more extensive" JSON syntax by adding the "X-Nimbu-Client-Version" header in the http headers of the request. You will then see that references, select and multi-select fields get more information back.
You can upload a file field as follows:
{
"field-with-files": {
"__type": "File",
"attachment":"... base64 encoded file data ..."
"filename": "example.pdf"
}
}
You can delete a file from an object as follows
{
"field-with-files": {
"__type": "File",
"remove": true
}
}
Each object contains two special fields that influence the default ACL on a channel, product or customer:
_owner: contains the id of the customer that owns the object_acl: contains a hash containing the read, update and delete permissionsAn example of a valid _acl object:
{
"*" => {
"read" => true,
"update" => false,
"delete" => false
},
"id:4fb97241b3893b3044000001" => {
"read" => true,
"update" => true,
"delete" => true
},
"role:Collaborator" => {
"read" => true,
"update" => true,
"delete" => false
}
}
The different API andpoints are shielded by multiple scopes:
read_site: read-only access to site settingsread_content: read-only access to content (pages, navigation, copywriting, media)read_channels: read-only access to channels and entries (excluding sensitive channels)read_sensitive_channels: read-only access to sensitive (as configured in the backend) channels and entriesread_themes: read-only access to your site themes, templates, layouts and snippetsread_cloudcode: read-only access to the source of your site cloud code and application logsread_products: read-only access to your products and collectionsread_customers: read-only access to your user / customer dataread_orders: read-only access to your ordersread_coupons: read-only access to your couponsread_devices: read-only access to the devices (push-notification tokens) registered with your sitewrite_site: write access to site settingswrite_content: write access to content (pages, navigation, copywriting, media)write_channels: write access to channels and entries (excluding sensitive channels)write_sensitive_channels: write access to sensitive (as configured in the backend) channels and entrieswrite_themes: write access to your site themes, templates, layouts and snippetswrite_cloudcode: write access to the source of your site cloud codewrite_products: write access to your products and collectionswrite_customers: write access to your user / customer datawrite_orders: write access to your orders and order stateswrite_coupons: write access to your couponswrite_devices: registration access for devices (push-notification tokens)skip_confirmation: allows to register or upload customers that are activated without email checkread_account: read-only access about the Nimbu accounts you have access toopenid:email:profile:full_profile: