Orangepill Docs
Search
K
Comment on page

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
admin
Create and update users and entities. Can manage deleted entities.
manage
Create and update users and entities.
user
Create and update entities.

Scopes

User is limited in it's scope to access data.
User scopes:
Scope
Description
realm
Access to realm entities.
own
Access to own entities.

Cumulative Permissions

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.

API scopes

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.

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 entitites by query.

Parameters

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

REST endpoint

GET {serviceName}/all

Results

[
{
id: "akTRSKTKzGCg9EMz",
...
},
{
id: "0YZQR0oqyjKILaRn",
...
}
]

list List entities

List entities with pagination. It returns also the total number of rows.

Parameters

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

REST endpoint

GET {serviceName}

Results

{
rows: [
{
id: "2bUwg4Driim3wRhg",
...,
},
{
id: "Di5T8svHC9nT6MTj",
...,
},
{
id: "YVdnh5oQCyEIRja0",
...,
},
],
total: 3,
page: 1,
pageSize: 10,
totalPages: 1,
}

count Count entities

Get the number of entities by query.

Parameters

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

REST endpoint

GET {serviceName}/count

Results

15

get Get an entity by ID

Get an entity by ID.

Parameters

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.

REST endpoint

GET {serviceName}/{id}

Results

{
id: "YVdnh5oQCyEIRja0",
...,
}