Overview
Features of Orangepill RESTful API.
Idempotency
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-tolerant
Client 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.
Security
x-api-key
The HTTP x-api-key
request header field must be used to identify Realm.
Authorization
Add Authorization
request header with x-api-key: base64encode(realm.key:username:password)
value.
Ownership
Each created entity is flagged with owner: authenticated_user.id
thus enabling automatic scope filtering and ownership.
Roles
User can have different roles in a realm.
Role | Description |
---|---|
| Create and update users and entities. Can manage deleted entities. |
| Create and update users and entities. |
| Create and update entities. |
Scopes
User is limited in it's scope to access data.
User scopes:
Scope | Description |
---|---|
| Access to realm entities. |
| Access to own entities. |
Cumulative Permissions
Role, Scope | Permission |
---|---|
| Can read owned entities. Can write owned entities. Can delete owned entities. Cannot delete owned user. Cannot undelete. Cannot create users. |
| Can read all entities. Can write owned entities. Can delete owned entities. Cannot delete owned user. Cannot undelete. Cannot create users. |
| Can read owned entities. Can write owned entities. Can delete owned entities. Can delete owned user. Can undelete owned. Cannot create users. |
| Can read all entities. Can update all entities. Can delete all entities. Can delete all users. Can undelete all. Cannot create users. |
| Can read owned entities. Can write owned entities. Can delete own entities. Can delete own user. Can undelete own. Can create users. |
| Can read all entities. Can write all entities. Can delete all entities. Can delete all users. Can undelete all. Can create users. |
API scopes
When calling API you can apply following scopes on entities.
Scope | Description |
---|---|
| Entities where current user is owner. |
| All realm entities. |
| Applies only for transactions. Transactions where current user is owner of destination account. |
| Applies only for transactions. Transactions where current user is owner of source account. |
| Deleted entities. |
Soft delete
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.
RESTful
Orangepill API is completely RESTful thus being interface for buidling frontend and backend apps.
find
Find entities
find
Find entitiesFind entitites by query.
Parameters
Property | Type | Default | Description |
---|---|---|---|
|
|
| Max count of rows. |
|
|
| Number of skipped rows. |
|
|
| Fields to return. |
|
|
| Sorted fields. |
|
|
| Search text. |
|
|
| Fields for search. |
|
|
| Scopes for the query. If |
|
|
| Populated fields. |
|
|
| Query object. If |
REST endpoint
Results
list
List entities
list
List entitiesList entities with pagination. It returns also the total number of rows.
Parameters
Property | Type | Default | Description |
---|---|---|---|
|
|
| Page number. |
|
|
| Size of a page. |
|
|
| Fields to return. |
|
|
| Sorted fields. |
|
|
| Search text. |
|
|
| Fields for search. |
|
|
| Scopes for the query. If |
|
|
| Populated fields. |
|
|
| Query object. If |
REST endpoint
Results
count
Count entities
count
Count entitiesGet the number of entities by query.
Parameters
Property | Type | Default | Description |
---|---|---|---|
|
|
| Search text. |
|
|
| Fields for search. |
|
|
| Scopes for the query. If |
|
|
| Query object. If |
REST endpoint
Results
get
Get an entity by ID
get
Get an entity by IDGet an entity by ID.
Parameters
Property | Type | Default | Description |
---|---|---|---|
|
|
| ID of the entity. The name of the property comes from the primary key field. |
|
|
| Fields to return. |
|
|
| Scopes for the query. If |
|
|
| Populated fields. |
REST endpoint
Results
Last updated