Comment on page
Overview
Features of Orangepill RESTful API.
The HTTP
idempotency-key request header field can be used to carry idempotency key in order to make non-idempotent HTTP methods such as POST or PATCH fault-tolerantClient can make the same request repeatedly because of network error, timeout etc.. but the same operation will not be executed twice. If Client repeats the same request by sending the same Idempotency Key value in request headers, and the request will be responded with the same response as the original request.
Name of the request header is
idempotency-key.Usage of Idempotency is optional.
The HTTP
x-api-key request header field must be used to identify Realm.Add
Authorization request header with x-api-key: base64encode(realm.key:username:password) value.Each created entity is flagged with
owner: authenticated_user.id thus enabling automatic scope filtering and ownership.User can have different roles in a realm.
Role | Description |
|---|---|
admin | Create and update users and entities. Can manage deleted entities. |
manage | Create and update users and entities. |
user | Create and update entities. |
User is limited in it's scope to access data.
User scopes:
Scope | Description |
|---|---|
realm | Access to realm entities. |
own | Access to own entities. |
Role, Scope | Permission |
|---|---|
user,own | Can read owned entities.
Can write owned entities.
Can delete owned entities.
Cannot delete owned user.
Cannot undelete.
Cannot create users. |
user,realm | Can read all entities.
Can write owned entities.
Can delete owned entities.
Cannot delete owned user.
Cannot undelete.
Cannot create users. |
manage,own | Can read owned entities.
Can write owned entities.
Can delete owned entities.
Can delete owned user.
Can undelete owned.
Cannot create users. |
manage,realm | Can read all entities.
Can update all entities.
Can delete all entities.
Can delete all users.
Can undelete all.
Cannot create users. |
admin,own | Can read owned entities.
Can write owned entities.
Can delete own entities.
Can delete own user.
Can undelete own.
Can create users. |
admin,realm | Can read all entities.
Can write all entities.
Can delete all entities.
Can delete all users.
Can undelete all.
Can create users. |
When calling API you can apply following scopes on entities.
Scope | Description |
|---|---|
own (default) | Entities where current user is owner. |
all | All realm entities. |
incoming | Applies only for transactions. Transactions where current user is owner of destination account. |
outgoing | Applies only for transactions. Transactions where current user is owner of source account. |
deleted | Deleted entities. |
Entities are never physically deleted, hence soft delete mechanism is applied. When
DELETE method is invoked on REST API interface, Orangepill middleware will flag the entity as deleted: true, and timestamped as deleted_at: Date.now(). Entities marked as deleted are filtered out from scopes all and own. To view deleted entities either disable scopes by adding ?scope=false to URL query or choose ?scope=deleted if exists for specific endpoint.Orangepill API is completely RESTful thus being interface for buidling frontend and backend apps.
Find entitites by query.
Property | Type | Default | Description |
|---|---|---|---|
limit | Number | null | Max count of rows. |
offset | Number | null | Number of skipped rows. |
fields | String|Array<String> | null | Fields to return. |
sort | String|Array<String> | null | Sorted fields. |
search | String | null | Search text. |
searchFields | String|Array<String> | null | Fields for search. |
scope | String|Array<String>|Boolean | null | Scopes for the query. If false, the default scopes are disabled. |
populate | String|Array<String> | null | Populated fields. |
query | String|Object | null | Query object. If String, it will be converted with JSON.parse |
GET {serviceName}/all
[
{
id: "akTRSKTKzGCg9EMz",
...
},
{
id: "0YZQR0oqyjKILaRn",
...
}
]
List entities with pagination. It returns also the total number of rows.
Property | Type | Default | Description |
|---|---|---|---|
page | Number | null | Page number. |
pageSize | Number | null | Size of a page. |
fields | String|Array<String> | null | Fields to return. |
sort | String|Array<String> | null | Sorted fields. |
search | String | null | Search text. |
searchFields | String|Array<String> | null | Fields for search. |
scope | String|Array<String>|Boolean | null | Scopes for the query. If false, the default scopes are disabled. Example: ?scope=-own,all removes own scope, and adds all. |
populate | String|Array<String> | null | Populated fields. |
query | String|Object | null | Query object. If String, it's converted with JSON.parse |
GET {serviceName}
{
rows: [
{
id: "2bUwg4Driim3wRhg",
...,
},
{
id: "Di5T8svHC9nT6MTj",
...,
},
{
id: "YVdnh5oQCyEIRja0",
...,
},
],
total: 3,
page: 1,
pageSize: 10,
totalPages: 1,
}
Get the number of entities by query.
Property | Type | Default | Description |
|---|---|---|---|
search | String | null | Search text. |
searchFields | String|Array<String> | null | Fields for search. |
scope | String|Array<String>|Boolean | null | Scopes for the query. If false, the default scopes are disabled. |
query | String|Object | null | Query object. If String, it's converted with JSON.parse |
GET {serviceName}/count
15
Get an entity by ID.
Property | Type | Default | Description |
|---|---|---|---|
<id> | any | null | ID of the entity. The name of the property comes from the primary key field. |
fields | String|Array<String> | null | Fields to return. |
scope | String|Array<String>|Boolean | null | Scopes for the query. If false, the default scopes are disabled. |
populate | String|Array<String> | null | Populated fields. |
GET {serviceName}/{id}
{
id: "YVdnh5oQCyEIRja0",
...,
}
Last modified 1mo ago