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",
    ...,
}