The authentication flows for services acting on a client’s behalf and browser based applications differ as described in the following.
+
+
API Keys
+
+
calls that do not need to identify a particular user, you can use an application API key.
+This is useful for server-side applications, or web applications that do not require the user to sign in with Google.
+
+
+
+
+
API Key Endpoint
+
+
+
The api key endpoint is usually mapped to:
+
+
+
+
{api domain}/api_keys/
+
+
+
+
Make sure you always use TLS for any request to the api key endpoint.
+Note that TLS is only available on the sub domain of invend.eu and not on DNS aliases.
+
+
+
+
+
Generating an API Key
+
+
+
An authorized user is allowed to generate an api key by using the endpoint.
+
+
+
A request for generating an API key has the following form:
The key property of created api_key resource can be used to perform authenticated requests against the API.
+The key is sent using the HTTP Authorization header.
+A request using an access token has this form:
+
+
+
+
GET /{resource path} HTTP/1.1
+Host: {api domain}.invend.eu
+Authorization: {api_key}
+
+
+
+
+
+
Invalidating an API Key
+
+
+
In order to invalidate the api key, DELETE against the api key endpoint with a valid bearer token authorization header as with normal API requests like this:
Please contact us if you want to integrate Invend with your cloud service.
+
+
+
+
+
OAuth 2 Authentication for Resource Owners
+
+
+
+
Access restricted resources require clients to be authenticated when accessing them.
+The API uses the OAuth 2 protocol for authentication.
+
+
+
+
+
Token Endpoint
+
+
+
The token endpoint is usually mapped to:
+
+
+
+
{api domain}/oauth2/token
+
+
+
+
Make sure you always use TLS for any request to the token endpoint.
+Note that TLS is only available on the sub domain of invend.eu and not on DNS aliases.
+
+
+
+
+
+
+
+
+Tokens might have read/ write access and should be treated like passwords.
+
The corresponding OAuth flow provides an optional token endpoint protection employing the Client Password authentication scheme or the HTTP Basic Authentication scheme.
+The former corresponds to the client_id/ client_secret parameter pair.
+As the user takes both OAuth defined roles, the resource owner and the client application roles, in this scenario, they are not used.
+As there is no intermediary party involved in the authentication flow, the client can safely send his credentials directly to the server.
+
+
+
A request for an authentication has the following form:
The expires_in property holds the number of seconds the access token is valid.
+By default, access tokens have a life time of four hours and refresh tokens of one year.
GET /{resource path} HTTP/1.1
+Host: {api domain}.invend.eu
+Authorization: Bearer {access_token}
+
+
+
+
+
+
Refreshing an Access Token
+
+
+
Expired access tokens can be refreshed using the refresh token.
+In order to stay authenticated, a refresh attempt should be started 25 minutes before the token expires and then re-tried every five minutes if it fails for technical reasons like unavailable Internet connection or server side errors.
A new refresh token is issued;
+the client must discard the old refresh token and replace it with the new one.
+The response has the same form as with an initial authentication.
+
+
+
+
+
Permanent Log-Ins
+
+
+
Users may choose to stay logged-in with their current device/ user agent beyond their use of an app.
+Therefore we recommend to persist the token information in the user agent’s local storage facility.
+
+
+
+
+
Invalidating Tokens
+
+
+
In order to invalidate the access token and effectively log out, DELETE against the token endpoint with a valid bearer token authorization header as with normal API requests like this:
The response body is empty.
+This request also invalidates the corresponding refresh token.
+
+
+
+
+
+
+
+
+Make sure that you destroy any token information stored on client-side.
+
+
+
+
+
+
+
+
Error Responses
+
+
+
Token Endpoint
+
+
If the request is syntactically incorrect or carries invalid credentials, an error response in accordance to the error response section in the OAuth 2 specification is generated.
+
+
+
The format of error responses strictly adheres to the OAuth 2 specification and differs from the others in this API.
+
+
+
In the following some possible error scenarios are exemplified.
+
+
+
A bad request (missing parameter in this case) is responded to with:
The user resource supports a query string parameter me to identify the matching user resource for the current request.
+This is useful if a client wants to check the status of an authentication token.
+For example:
+
+
+
+
https://meta.invend.eu/users/?me
+
+
+
+
The response is a collection with a single entry.
+
+
+
+
+
Account Security
+
+
+
The following measures are taken to prevent accounts from being compromised:
+
+
+
+
+
Passwords must not be shorter than eight characters.
+
+
+
After 10 subsequent failed login attempts, the account is locked for 10 seconds to hinder brute force attacks.
+
+
+
OAuth 2 access tokens with limited validity require regular token refresh.
+This limits the potential damage imposed by a leaked access token.
+
+
+
Permanent logins based on tokens should be persisted in the user agent’s local storage instead of cookies which are subject to domain based sniffing an CSRF.
Data privacy protection through fine-grained access control is a key feature of Invend based APIs.
+Read more about the powerful Attribute Based Access Control concepts employed.
+Access can be restricted by the following orthogonal dimensions which are explained in detail below:
+
+
+
+
+
Resource
+
+
+
Operation modification semantics
+
+
+
Ownership scope
+
+
+
+
+
The general process to implement access restrictions for an API is:
+
+
+
+
+
Define business roles. Define the business roles that your application requires.
+For example, you might create roles for unauthenticated users, customers, and administrators.
+
+
+
Define the rules of a business role. For example, you might allow unauthenticated users to read products, but disallow modifications of them.
+Every action not explicitly allowed by a rule is denied.
+
+
+
Grant business roles. Business roles are the authorization currency and grantees are enabled to perform the defined actions.
+
+
+
+
+
code in this section denote the values which are used in the JSON based policy definition syntax.
+
+
+
+
+
Resource
+
+
+
Resources are the fundamental elements in a Web API.
+See how to define resources.
+The IRI of such a resource is used to refer to the resource definition with the res property.
+
+
+
+
+
Operation Modification Semantics
+
+
+
The following mapping shows the basic resource operations, their HTTP methods and their corresponding identifier for the modification semantics used in the policy language:
+
+
+
+
+
+
+
+
+
+
Operation
+
HTTP Method
+
Modification Semantics
+
+
+
+
+
AppendResourceOperation
+
POST
+
c
+
+
+
CreateOrReplaceOperation</span>
+
PUT
+
c
+
+
+
RetrieveResourceOperation
+
GET
+
r
+
+
+
UpdateResourceOperation
+
PATCH
+
u
+
+
+
DeleteResourceOperation
+
DELETE
+
d
+
+
+
+
+
+
+
Ownership Scope
+
+
+
The ownership scope can be set to the following values with the given meaning:
+
+
+
+
+
user: resources owned by a user,
+
+
+
org: resources owned by an organization,
+
+
+
app: resources belonging to an application (everything below a domain).
+
+
+
+
+
These scopes have the following set relations: user ⊂
+org ⊂
+app.
+This hierarchy is considered when authorization decisions are made.
+
+
+
For example access is granted if access is requested in the user scope but the subject is actually granted in the app scope as the user scope is included in the app scope.
+
+
+
Possessive Properties
+
+
Some of these scopes require possessive properties to be present on resources to take effect.
+Such properties allow to identify the owner of a resource.
+
+
+
+
+
+
+
+
+If an access restriction is defined which corresponds to a possessive property and is missing in a resource instance, the restrictions will not take effect.
+
+
+
+
+
+
The following property types are supported as possessive properties:
+
+
+
+
+
dct:creator for user and org which take the IRI of a user or organization as value.
+
+
+
The application is implicitly known by the domain part of the resource IRI.
+
+
+
+
+
+
Scope Instances
+
+
When access restrictions are enforced, scopes can only take effect in combination with a scope instance which is the IRI of a resource corresponding to the scope.
+The ownership scopes correspond to the following resource types:
+
+
+
+
+
user: User resource,
+
+
+
org: Organization resource,
+
+
+
app: Application resource.
+
+
+
+
+
+
+
+
Business Roles
+
+
+
Business roles (usually mapped to /business_roles/) are used to specify constraints expressed in the aforementioned dimensions in a JSON-based DSL which has the following format:
A BR contains a policy with a set of rules about which modification semantics, defined by the mask property, a grantee can apply to the resource res in the scope scope.
+There might be multiple rules for a resource.
+
+
+
Business roles can freely be modeled according to your needs.
+For example to model the organizational structure of a sales division in a company, a 'generalmanager', 'salesmanager' or 'salesman' might be introduced for an application.
+
+
+
+
+
Granting Business Roles
+
+
+
Business roles are granted to users with the businessRoles property on a user resource like so:
This BR assignment tells the authorization layer which scope instance should be applied for any rule with the given scope for the given BR.
+From a business perspective you could say that the user takes up the BR within the given scope (application, org or user).
+If no instance is defined for the scope user like in this example, the current user is assumed as scope instance;
+this is natural as a user should be able to access resources created by him.
+
+
+
The scope of the assignment does not grant or limit any permissions to the user it is merely to define the type of the instances for the corresponding scope in the BR rules.
+
+
+
+
+
Business Role Delegation
+
+
+
The basic principle is natural: A resource owner may grant other clients access to them.
+The granting of BRs is limited by the BR’s grantable property which allows to define BRs whose grantees may grant the BR to other users.
+As an example, this definition of a BR would allow only the holder of the appadmin BR to grant the BR to other users and the assignment is bound to to the scope app with instance app-x:
A delegatable BR can be created by allowing the grantees of a BR to grant it.
+This must explicitly allowed by setting the delegatable flag to true on the assignment.
+
+
+
+
How are Access Restrictions enforced?
+
+
+
+
To take full advantage of Invend’s authorization capabilities, it is beneficial to understand how access restrictions are enforced.
+
+
+
+
+
Scope and Instance Determination
+
+
+
How does the API determine the ownership scope that a client tries to access?
+
+
+
Automatically, the most permissive scope the client is allowed to access is selected implicitly.
+The following scope instances are selected for the respective scopes:
+
+
+
+
+
user: defaults to the user IRI of the user conducting the request,
+
+
+
org: defaults to the IRI of user’s organization,
+
+
+
app: defaults to the IRI of the accessed application.
+
+
+
+
+
Scopes and scope instances can also be explicitly defined per request as described in XXX.
+Explicit scope definition is usually not required.
+
+
+
+
+
Decision Algorithm
+
+
+
The following properties of a request are taken into account to make an authorization decision:
+
+
+
+
+
The accessed application.
+
+
+
The accessed resource.
+
+
+
The modification semantics of the performed operation.
+(according to the HTTP method).
+
+
+
The access scope and the associated scope instance, if explicitly specified.
+
+
+
The subject accessing the resource.
+
+
+
The definitions of the BRs assigned to the user/ subject.
+
+
+
+
+
With this information, the authentication layer makes a per-request decision.
+
+
+
+
+
Unauthenticated User
+
+
+
An application may define an unauthenticated user using the unauthUser which may receive business roles as any other user allowing for fine-grained access control for public APIs and conversely, to create private applications.
Data privacy protection through fine-grained access control is a key feature of Invend based APIs.
+Read more about the powerful Attribute Based Access Control concepts employed.
+Access can be restricted by the following orthogonal dimensions which are explained in detail below:
+
+
+
+
+
Resource
+
+
+
Operation modification semantics
+
+
+
Ownership scope
+
+
+
+
+
The general process to implement access restrictions for an API is:
+
+
+
+
+
Define business roles. Define the business roles that your application requires.
+For example, you might create roles for unauthenticated users, customers, and administrators.
+
+
+
Define the rules of a business role. For example, you might allow unauthenticated users to read products, but disallow modifications of them.
+Every action not explicitly allowed by a rule is denied.
+
+
+
Grant business roles. Business roles are the authorization currency and guarantees are enabled to perform the defined actions.
+
+
+
+
+
code in this section denote the values which are used in the JSON based policy definition syntax.
+
+
+
+
+
Resource
+
+
+
Resources are the fundamental elements in a Web API.
+See how to define resources.
+The IRI of such a resource is used to refer to the resource definition with the res property.
+
+
+
+
+
+
+
+
+The IRI of resource collection refer to all resources.
+
+
+
+
+
+
+
+
Operation
+
+
+
The following mapping shows the basic resource operations, their HTTP methods and their corresponding IRI used in the policy language:
Operation
+
HTTP Method
+
Modification Semantics
+
AppendResourceOperation
+
POST
+
CreateOrReplaceOperation</span>
+
PUT
+
RetrieveResourceOperation
+
GET
+
UpdateResourceOperation
+
PATCH
+
DeleteResourceOperation
+
DELETE
+
+
+
+
+
+
+
+
+If the value of operation property is an empty array, no access is granted.
+
+
+
+
+
+
Blank Operation
+
+
An blank hydra operation blank node is used to mapping a group of resource operations with a definite hydra method, which has the following format:
+
+
+
+
"operation": [
+ {
+ "method": "GET"
+ }
+ ...
+]
+
+
+
+
Access is granted to all operations which has the same hydra method as in the set of rules.
+
+
+
+
Extended Operation
+
+
Extended operations can be set in the policies explicitly by using IRI.
+
+
+
+
+
+
Ownership Scope
+
+
+
The ownership scope can be set to the following values with the given meaning:
+
+
+
+
+
user: resources owned by a user,
+
+
+
org: resources owned by an organization,
+
+
+
app: resources belonging to an application (everything below a domain).
+
+
+
+
+
These scopes have the following set relations: user ⊂
+org ⊂
+app.
+This hierarchy is considered when authorization decisions are made.
+
+
+
For example access is granted if access is requested in the user scope but the subject is actually granted in the app scope as the user scope is included in the app scope.
+
+
+
Possessive Properties
+
+
Some of these scopes require possessive properties to be present on resources to take effect.
+Such properties allow to identify the owner of a resource.
+
+
+
+
+
+
+
+
+If an access restriction is defined which corresponds to a possessive property and is missing in a resource instance, the restrictions will not take effect.
+
+
+
+
+
+
The following property types are supported as possessive properties:
+
+
+
+
+
dct:creator for user and org which take the IRI of a user or organization as value.
+
+
+
The application is implicitly known by the domain part of the resource IRI.
+
+
+
+
+
+
Scope Instances
+
+
When access restrictions are enforced, scopes can only take effect in combination with a scope instance which is the IRI of a resource corresponding to the scope.
+The ownership scopes correspond to the following resource types:
+
+
+
+
+
user: User resource,
+
+
+
org: Organization resource,
+
+
+
app: Application resource.
+
+
+
+
+
+
+
+
Business Roles
+
+
+
Business roles (usually mapped to /business_roles/) are used to specify constraints expressed in the aforementioned dimensions in a JSON-based DSL which has the following format:
A BR contains a policy with a set of rules about which operations, defined by the operation property, a guarantee can apply to the resource res in the scope scope.
+There might be multiple rules for a resource.
+Always the last rule for a resource wins.
+
+
+
+
+
+
+
+
+Only one rule in the policies will take effect per request.
+If the best match rule is found, all remains are not considered when authorization decision is made.
+
+
+
+
+
+
Business roles can freely be modeled according to your needs.
+For example to model the organizational structure of a sales division in a company, a 'generalmanager', 'salesmanager' or 'salesman' might be introduced for an application.
+
+
+
+
+
Granting Business Roles
+
+
+
Business roles are granted to users with the businessRoles property on a user resource like so:
This BR assignment tells the authorization layer which scope instance should be applied for any rule with the given scope for the given BR.
+From a business perspective you could say that the user takes up the BR within the given scope (application, org or user).
+If no instance is defined for the scope user like in this example, the current user is assumed as scope instance;
+this is natural as a user should be able to access resources created by him.
+
+
+
The scope of the assignment does not grant or limit any permissions to the user it is merely to define the type of the instances for the corresponding scope in the BR rules.
+
+
+
+
+
Business Role Delegation
+
+
+
The basic principle is natural: A resource owner may grant other clients access to them.
+The granting of BRs is limited by the BR’s grantable property which allows to define BRs whose grantees may grant the BR to other users.
+As an example, this definition of a BR would allow only the holder of the appadmin BR to grant the BR to other users and the assignment is bound to to the scope app with instance app-x:
A delegatable BR can be created by allowing the grantees of a BR to grant it.
+This must explicitly allowed by setting the delegatable flag to true on the assignment.
+
+
+
+
How are Access Restrictions enforced?
+
+
+
+
To take full advantage of Invend’s authorization capabilities, it is beneficial to understand how access restrictions are enforced.
+
+
+
+
+
Scope and Instance Determination
+
+
+
How does the API determine the ownership scope that a client tries to access?
+
+
+
Automatically, the most permissive scope the client is allowed to access is selected implicitly.
+The following scope instances are selected for the respective scopes:
+
+
+
+
+
user: defaults to the user IRI of the user conducting the request,
+
+
+
org: defaults to the IRI of user’s organization,
+
+
+
app: defaults to the IRI of the accessed application.
+
+
+
+
+
Scopes and scope instances can also be explicitly defined per request as described in XXX.
+Explicit scope definition is usually not required.
+
+
+
+
+
Decision Algorithm
+
+
+
The following properties of a request are taken into account to make an authorization decision:
+
+
+
+
+
The accessed application.
+
+
+
The accessed resource.
+
+
+
The hydra method, if explicitly specified.
+
+
+
The performed operation, if explicitly specified.
+
+
+
The access scope and the associated scope instance, if explicitly specified.
+
+
+
The subject accessing the resource.
+
+
+
The definitions of the BRs assigned to the user/ subject.
+
+
+
+
+
With this information, the authentication layer makes a per-request decision.
+
+
+
+
+
Unauthenticated User
+
+
+
An application may define an unauthenticated user using the unauthUser which may receive business roles as any other user allowing for fine-grained access control for public APIs and conversely, to create private applications.
Data hosted on Invend is exposed as resources accessible through a uniform hypermedia API which allows retrieval and manipulation.
+The API-entry-point is either the application’s ID as subdomain of invend.eu — called API domain, or a DNS CNAME alias which of it:
+
+
+
{app ID}.invend.eu
+
+
+
The API follows the REST architectural model.
+Resources are acted upon with HTTP action methods (verbs) having the following purpose:
HTTP Method
+
Description
+
OPTION
+
Used for preflight requests in a CORS scenario (see XXX).
+
HEAD</span>
+
Just get the HTTP header info.
+
GET
+
Read a resource.
+
POST
+
Append a resource to the specified collection (an identifier is
+ generated by the server).
+
Perform resource specific operations such as
+ initiating a password reset process for a user.
+
PUT
+
Create or replace a resource with a given identifier.
+
PATCH
+
Partially update a resource (add, remove or overwrite single
+ properties of the resource).
+
DELETE
+
Delete a resource.
+
+
+
Resources reside on the server.
+Client and server exchange representations of these resources as HTTP body data.
+In the following, the term resource is used as abbreviation of resource representation.
+
+
+
+
+
Data Transport, Encoding and Format
+
+
+
HTTP 1.1 Protocol
+
+
HTTP 1.1 is used to transfer data and should be used in favor of 1.0.
+
+
+
+
HTTPS protected Transport
+
+
Data privacy is ensured by using the HTTP over TLS — the HTTPS protocol.
+
+
+
TLS is only available on the API domain and not on DNS aliases.
+
+
+
+
SPDY Extension
+
+
The SPDY protocol (baed on TLS, HTTP) used if supported by the client.
+SPDY is a precursor of HTTP 2.0 and yields better performance in terms of latency.
Linked data resources are serialized in JSON-LD, a format to serialize Linked Data based on JSON and transferred in the HTTP body with the MIME media type application/ld+json.
+No other serialization formats such as XML or Turtle are supported for linked resources at this time.
+
+
+
+
ISO Time and Date Format
+
+
If not specified otherwise, all date values are ISO-8601 formatted and represented in the UTC time zone: {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}.{SSS}{TZ}.
+An example date string: 2014-08-31T12:00:00.000Z
+
+
+
+
+
+
Internationalized Resource Identifiers
+
+
+
Resources itself and many other concepts such as types and classes are identified by Internationalized Resource Identifiers (IRI).
+An IRI in short is a generalized URI with a less restrictive character set.
+
+
+
IRIs are treated as RFC3986 URI reference and thus relative references are resolved according to the corresponding reference resolution rules.
+In general absolute and relative forms can be distinguished.
+Relative IRIs might be relative to a collection or the API domain (authority part of the IRI).
+
+
+
For reference resolution, the following ways to define the base IRIs, against which the relative reference is applied, are supported in order of precedence:
+
+
+
+
+
Base IRI embedded in content via the @base property for LD resources.
+
+
+
IRI used to access the resource.
+
+
+
Default base IRI which is defined by in the resource model (API domain and path property).
+
+
+
+
+
The server validates client provided IRIs in cases where ambiguous may exist and informs the client accordingly.
+
+
+
+
Interacting with Resources through Operations
+
+
+
+
This section describes how to interact with resources through operations.
+The description of these affordances is based on Hydra Core — an emergeing vocabulary to describe Web APIs.
+
+
+
+
+
CRUD Operations
+
+
+
The basic operations to create, read, update and delete a resource are shared by all resource types.
+The following table provides an overview of the operations, mapping to HTTP methods and their modification semantics.
+
+
+
+
+
+
+
+
+
+
Operation
+
HTTP Method
+
Modification Semantics
+
+
+
+
+
RetrieveResourceOperation
+
GET
+
read
+
+
+
AppendResourceOperation</span>
+
POST
+
create
+
+
+
CreateOrReplaceOperation
+
PUT
+
create
+
+
+
UpdateResourceOperation
+
PATCH
+
update
+
+
+
DeleteResourceOperation
+
DELETE
+
delete
+
+
+
+
+
Operations do not obsolete the HTTP methods like GET — they are just mapped to them to have a formal identifier for those operations which can be referred to.
+
+
+
Operations supported by a resource are announced in the operation property.
+For example a client having read and write access to an address resource receives this when getting a resource:
These headers are omitted in the following examples to keep them brief.
+
+
+
+
+
Response Codes
+
+
+
Responses carry a meaningful HTTP status code and a response body.
+API consumers must interpret the HTTP response code as outcome of the request and react accordingly.
+All supported status codes are listed in the following table:
HTTP Status Code
+
Description
+
200 OK
+
The operation was successful.
+
204 No Content
+
The operation was successful but the server did not return any content.
+ For resource updates: returned when the key already existed and the
+ file was replaced with what you sent.
+
301 Moved Permanently
+
The requested resource has been assigned a new permanent URI
+ and any future references to this resource should use one of
+ the returned URIs.
+
303 See Other
+
The resource was created.
+ The Location header contains the URL to query the newly
+ created resource.
+
400 Bad Request
+
The submitted data in the request body or the query string parameters are
+ syntactically incorrect or invalid in terms of format.
+
401 Unauthorized
+
No or invalid authentication credentials have been provided
+
402 Payment Required
+
A payment according to the contract with the provider of Invend is required
+
403 Forbidden
+
A request has been made from an origin domain which is not
+ granted to issue CORS requests.This might be the case if the
+ application domain is not or nor correctly registered.
+
Although the provided authentication information were valid,
+ the client is not granted to perform the requested operation on
+ the resource
+
404 Not Found
+
The requested resource could not be found.
+
406 Not Acceptable
+
An unsupported response format was requested.
+
415 Unsupported Media Type
+
Data has been sent in an unsupported format.
+
409 Conflict
+
A resource with the provided ID already exists.
+
413 Request Entity Too Large
+
Request size limit exceeded.
+
429 Too Many Requests
+
Rate limit exceeded.
+
500 Internal Server Error
+
An internal error on the server occurred.
+
503 Service Unavailable
+
We are temporarily unable to return the representation.
+ Try again in a reasonable amount of time.
+
+
+
+
+
Error Responses
+
+
+
Client errors are denoted by a 4xx status code, sever errors by a 5xx.
+For some errors, also the body should be interpreted to derive a cause.
+
+
+
A request yielding an error results in a response like this:
+
+
+
+
{
+ "@context": {
+ "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+ "hydra": "http://www.w3.org/ns/hydra/core#",
+ "dct": "http://www.w3.org/ns/hydra/core#",
+ "Error": "hydra:Error",
+ "date": "dct:created",
+ "request": "dct:identifier",
+ "statusCode": "hydra:statusCode",
+ "title": "hydra:title",
+ "description": "hydra:description",
+ "seeAlso": { "@id": "rdfs:seeAlso", "@type": "@id" },
+ },
+ "@type": "Error",
+ "date": "2014-03-13T19:43:18.139Z",
+ "request": "4d32dd9f-311b-47c6-97a3-8babf9b2d0b1",
+ "statusCode": 403,
+ "title": "Forbidden",
+ "description": "The provided authentication information were valid but permission based on your credentials is not granted to perform the requested operation.",
+ "seeAlso": "https://dev.invend.eu"
+}
+
+
+
+
+
Content Negotiation
+
+
+
+
The API strictly adheres to the content negotiation principle of HTTP.
+While the content representation (via the content type headers) is defined above, this section deals with the negotiable aspects of the content itself.
+
+
+
+
+
Multilingual Resources
+
+
+
Subject to negotiation are the values of properties which have language variants.
+Language tags are formatted according to the BCP 47 standard.
+Typically they consist of locale and an optional territory specific variant suffix.
+So a valid locale is for example: en-GB.
+
+
+
If a suffix (GB in this example) is given, the exact translation for this variant is tried to be resolved, if it does not exist, the base locale (en in this example) is used;
+The so-called fall back locale is only considered in the case of absence of both.
+There are the following ways to specify the preferred locale of which only the first is real HTTP based content negotiation.
+
+
+
Accept Language Header
+
+
Locales specified in the accept-language header are tried to be accorded to in the weighted order representing their priority.
+The primary locale is the one with the highest priority and the second priority is the fall back locale.
+If non of the primary locales can be resolved, the fall back locale is tried to be resolved.
+For the value en-us,de-de;q=0.8, en-US is used as primary locale and through the variant based fall back also en.
+de-DE as it is explicitly specified as second priority and thus the fall back locale.
+
+
+
+
Query String Parameters
+
+
There are the optional query string parameters locale and fallbackLocale which may be used if the corresponding HTTP request headers cannot be influenced.
+Each parameter takes a single language tag.
+The query string parameters take precedence over the corresponding headers.
+
+
+
+
Getting multiple Translations
+
+
Multiple translations at once can be retrieved with the locales query parameter.
+It accepts a colon separated list of the desired locales.
+
+
+
+
+
Client based Caching
+
+
+
+
All resource types are returned with the last-modified response header to enable clients to caching them.
+Clients may remember this date and make a conditional request using the request header if-modified-since: {date} for subsequent requests.
+
+
+
The last-modified date is derived from the date properties created and modified (both from the DC terms namespace) for LD resources.
+For collections of resources, the most recently changed entry is used as last-modified date.
+
+
+
Etags are not used by this API.
+
+
+
+
+
Exceptions
+
+
+
+
+
Files ending with .appcache are delivered as not cacheable to force user agents to check for updates.
+
+
+
+
+
+
Cross Origin Resource Sharing
+
+
+
+
Cross Origin Resource Sharing (CORS) is supported by the API and may be controlled by the API owner.
+The relevant header to denote the origin of a request is the origin header which must have a value of the form {proto}{fqdn}.
+The following CORS requests exemplify the outcomes of typical cases.
+
+
+
+
+
Example
+
+
+
A simple and allowed cross origin request which does not involve a preflight request looks like this:
Certain limits are lined up to prevent abuse of the API.
+
+
+
+
+
Request Rate
+
+
+
The request rate is limited per IP address at a maximum of 180 within a time window of 15 minutes.
+The following HTTP headers inform about the current call quota status:
+
+
+
+
+
+
+
+
+
Header Name
+
Description
+
+
+
+
+
X-Rate-Limit-Limit
+
The maximum number of requests that the consumer is permitted to make within a 15 minute window.
+
+
+
X-Rate-Limit-Remaining</span>
+
The number of requests remaining in the current rate limit window.
+
+
+
X-Rate-Limit-Reset
+
The time at which the current rate limit window resets in UTC epoch seconds.
+
+
+
+
+
If the call limit is hit, HTTP status code 429 is returned.
The size of an HTTP request body is limited depending on the type of the resource and the content type (content-type header) as shown below.
+If the limit is hit, HTTP status code 413 is returned and the request is cancelled.
+
+
+
Structured data resources:
+
+
+
+
+
application/*+json: 5.0 MiB.
+
+
+
application/x-www-form-urlencoded: 512 kiB.
+
+
+
+
+
Object data resources:
+
+
+
+
+
/: 5.0 GiB (object + meta data).
+
+
+
+
+
+
Seriously REST
+
+
+
+
In this section it is shown how some of the advanced aspects of REST are realized in the API.
+
+
+
+
+
Self-Descriptive Resources
+
+
+
Each resource corresponds to a type which is defined by means of JSON-LD’s feature to corece values to particular data types.
+The @type keyword is used to define the data type of:
+
+
+
+
+
a resource (graph node) — whose type is a concept typically defined as RDFS Class.
+
+
+
a value — whose type is a relation (or predicate) which is typically an RDFS Property or just a plain data type like XSD boolean.
+
+
+
+
+
For example obtaining the @type of the resource https://meta.invend.eu/timezones/ yields http://www.w3.org/ns/hydra/core#PagedCollection.
+Picking the resource http://www.w3.org/2006/timezone-world#ZTZ from this collection and inspecting its @type tells the client that it is of the type http://www.w3.org/2006/timezone#TimeZone.
+
+
+
Linked data and Semantic Web principles imply that a coerced type is an IRI which usually can be dereferenced.
+Type IRIs usually dereference to an entry in a formal vocabulary which define the unambiguous meaning of the class or property thus enabling a client to introspect a resource.
+
+
+
+
+
Hypermedia Support
+
+
+
Affordances (things that can be done with a resource or in the current state of the application) make an API a hypermedia — a nonlinear medium which can be browsed without prior knowledge.
+Hypermedia is the prerequisite to support REST’s HATEOAS constraint.
+Affordances can be differentiated in two types, hyperlinks and operations.
+How they materialize in the API is described in the following.
+
+
+
Hyperlinks
+
+
Resource interlinking a native feature of the JSON-LD data format which is used to represent resources.
+The @id keyword allows definition of links like this:
+
+
+
+
"website": { "@id": "http://www.invend.eu" }
+
+
+
+
This allows to distinguish links to other resources from data where IRIs are used exclusively as identifiers.
+
+
+
Property values can also be declared as hyperlink by the intrinsic semantics of the property.
+For example the property type http://schema.org/url denotes that its value is a URL.
+A client may use this knowledge accordingly.
+
+
+
+
Operations
+
+
As described above operations or controls are modeled using Hydra Core.
+
+
+
+
+
Machine Readable API Documentation
+
+
Machine Readable API Documentation
+
+
+
A machine readable API documentation expressed in the terms of Hydra Core, listing all availableresources and its operations is available through the corresponding resource.
+Usually it is mapped to /apidoc/.
+
+
+
+
Performance Tips
+
+
GZip Compression
+
+
+
An easy and convenient way to reduce the bandwidth needed for each request is to use Gzip compression.
+Although this consumes additional processing resources to uncompress data, the trade-off with reduced latencies usually makes it very worthwhile.
+
+
+
Data is generally served Gzip encoded, if the Accept-Encoding header contains the associated token.
+For example, a properly formed HTTP request header for receiving a Gzip encoded response is:
+
+
+
+
Accept-Encoding: gzip
+
+
+
+
To specify that multiple content encodings are acceptable, they can be concatenated as shown in RFC2616.
Multiple filters can be combined by colon separated concatenation.
+The filters are combined with a logical AND operation.
+Attributes are the schema defined names of the resource.
+The following comparators are supported:
+
+
+
+
+
: equality
+
+
+
<> inequality
+
+
+
< lower than
+
+
+
<: lower than equals
+
+
+
> greater than
+
+
+
>: greater than equals
+
+
+
+
+
For example:
+
+
+
+
?filters=created>2014,created<2014-10-01
+
+
+
+
returns all resources, that have been created between Jan.
+1st, 2014 and Oct.
+1st, 2014.
+By default no filters are applied.
+
+
+
Range values are supported for the equality comparator for numerical attributes only.
+A range value:
+
+
+
+
{min}..{max}
+
+
+
+
Min should be less than or equal to max.
+Min and max values are included in the range.
+For example:
+
+
+
+
?filters=price:100..500
+
+
+
+
returns all resources whose price attribute lies within the range from 100 to 500, inclusively.
+
+
+
+
+
Full Text Search
+
+
+
Full-text search within a resource is initiated by providing a single or multiple search terms with the ?s query string parameter on the endpoint of the collection of the resource:
+
+
+
+
{?s}
+
+
+
+
For example:
+
+
+
+
?s=germany
+
+
+
+
searches in the given resource for an item which has a property with the value 'germany'.
+The result is a collection with matching entries.
We embrace the fact that every business is different and the world is ever changing.
+We have designed the Restorecommerce with this awareness and want to enable you to build aspiring applications which can cope with this only constant at minimal effort.
+-- Thomas Hoppe
+
+
+
+
+
+
Architecture
+
+
+
+
In the following we describe the employed architectural principles and the building blocks of Restorecommerce.
+
+
+
+
+
Building Blocks
+
+
+
+
+
+
+
+
+
+
The Cloud, Microservices, Immutability
+
+
+
Restorecommerce is cloud native software which means it leverages contemporary deployment models such as containers and doesn’t solve problems which are already covered by typical cloud infrastructures.
+It grew up in the era of microservices and is therefore properly decomposed into such.
+Furthermore, it adheres to the principle of immutability whenever possible.
+This is a very powerful combination which makes Restorecommerce highly scalable and easy to evolve and to operate.
+
+
+
+
+
Semantic Web
+
+
+
Semantic web technologies are the answer to many prevailing computer science problems of the past decade, such as the high coupling in distributed systems or interoperability on a data level.
+We are convinced that most of the potential gains have not yet been realized.
+As semantic web technologies are part of Restorecommerce’s DNA, you can benefit from their advantages today and continue to do so in the future.
+
+
+
Generally, structured data in Restorecommerce is semantically tagged to maximize machine readability and data Interoperability.
+This becomes more-and-more important as search engines already understand semantically tagged data and continuously extend their capabilities in this regard.
+
+
+
+
+
Linked Data
+
+
+
Structured, machine readable data sets published on the web become linked data if they are interlinked by meaningful relations.
+The list of publicly funded projects, governmental institutions, research facilities and commercial organizations which participate in this Web of Data is constantly growing.
+Many data sets are also published as linked open data under licenses which allow a commercial use.
+The key principle is that resources are identified by IRIs (URLs) which can be resolved to obtain a representation of that resource (dereferencing).
+
+
+
Restorecommerce is built entirely on linked data principles and allows to use existing linked data sets and keep them in sync as they evolve.
+This is for example important for what we call data commons which describes master data sets such as countries, languages, or country specific taxes.
+This is common knowledge and exists already in a machine readable formats — we think nobody should be required to set up tax rates in an online shop anymore.
+
+
+
+
+
REST API
+
+
+
A Restorecommerce based application has its individual API which is based on a flexible resource model.
+The resource model is the blueprint of the API as it defines:
+
+
+
+
+
which resources and collections thereof exist,
+
+
+
to which paths they are mapped,
+
+
+
which affordances a resource exhibits,
+
+
+
the semantic mapping of the properties of resources.
+
+
+
+
+
The actual API is thus merely a reflection of the resource model.
+
+
+
API first! — every functionality in Restorecommerce is exposed as part of an API which strictly follows the REST architectural model.
+An API has the following notable qualities:
+
+
+
Coherence
+
+
We really want developers to only need to work with one API, be it for technical aspects or for business related functionality.
+Therefore, developers only need to learn the basic principles of an API once and are empowered to extrapolate it for its entirety.
+
+
+
+
Hypermedia
+
+
Hypermedia data formats such as HTML include links to allow its consumers to navigate within and between documents;
+Forms are embedded to allow manipulation of resources.
+A hypermedia API supports these principles on the API level.
+
+
+
Restorecommerce based APIs qualify as hypermedia capable because structured resources are represented in the JSON-LD format which inherently allows interlinking of resources.
+More complex affordances are modelled with Hydra Core.
+
+
+
+
Hydra Core
+
+
Hydra Core is a lightweight vocabulary for web APIs.
+It allows to enrich resources with affordances (things you can do with a resource at hand) which describe interactions beyond simple links and the simple CRUD semantics of HTTP methods.
+
+
+
+
+
+
Persistence Tier
+
+
+
Efficient storage and retrieval of data is the essential discipline to succeed with any kind of distributed system arrangement.
+
+
+
Flexible Resource Types
+
+
As there is no such thing as a universal storage model which can provide this for any scenario, Restorecommerce supports different types of resources.
+Currently structured data and object data based resources are the most relevant for web applications and both are supported.
+There is a corresponding storage service abstraction for each type:
+
+
+
Graph Storage Service
+
+
Almost every data model of a real-life problem is effectively graph based because as soon as links between entities are introduced they form a graph.
+Graphs are naturally the best fit when it comes to persisting data which contains links.
+This is why Restorecommerce offers a graph storage service to persist structured data.
+Each application operates on a dedicated, technically isolated graph whose nodes can connect to nodes in other graphs via links.
+
+
+
+
Object Storage Service
+
+
Object based data (blobs, files) such as static application assets or user provided content such as image uploads can be stored in object data resources.
+
+
+
+
Other Storage Services
+
+
Internally, there are two more types of storage engines used: There is an in-memory storage engine which is used to cache data and session information.
+A search index is used to enable complex querying and search on certain resources.
+These storage engines hold structured data as well, they just offer specialized access methods and characteristics which are beneficial for performance reasons.
+
+
+
+
+
+
+
Security
+
+
+
Data privacy and integrity is a key concern of Restorecommerce.
+We adhere to the security by design principle to lower the efforts of application providers to meet their security goals.
+
+
+
Restorecommerce features OAuth 2.0 authentication and an advanced Attribute Based Access ControlABAC authorization model.
+This allows for manageable fine-grained access control.
+
+
+
+
Client Interoperability
+
+
Client Interoperability
+
+
+
Any kind of client such as classical web sites, native mobile apps based on Android, iOS etc., desktop applications and fat clients can be integrated with or can be built based on Restorecommerce.
+
+
+
HTML5 apps based on the single page application architecture are particularly well suited as client of a hypermedia API as they inherently support JSON and Ajax.
A freshly installed system has no data. To populate it with example data, enter the data directory, run node import.js <API key>
+and choose which data set to import (API key is generated and output to logs by facade-srv at start).
+The corresponding microservices must be running locally, as well as the facade service.
The Restorecommerce platform is a free and Open Source e-commerce suite based on a modern architecture.
+It is highly modular and thus very flexible to base instantiate it
+for custom solutions. Be it a simple online shop or an event booking platform, we strive to create the best building blocks for
+a commerce experience of today.
+
+
+
+
+
Status
+
+
+
Currently, Restorecommerce is in phase of alpha maturity.
+There are, however, already systems based on the platform in production.
+If you want to use it at this stage, consider that changes to APIs are likely.
Common operational tasks are described in the following.
+
+
+
+
+
Backup
+
+
+
All state is persisted in stateful backing services.
+Some of those backing services are of ephermal nature, so they store information only temporarily, for a short time span.
+Also for some of them, data can be restored from other sources or is irrelevant when expired.
+Obviously, such services do not need to be backed up.
+This leaves the following persistence services which must be part of a full system backup:
+
+
+
+
+
Container volume for ArangoDB
+
+
+
Container volume for file based storage
+
+
+
+
+
The search index does not need to be backed up as it can be regenerated from GSS based data.
+
+
+
+
+
Upgrade
+
+
+
Each service of the system can be upgraded individually as long as the upgrade does not introduce a breaking API change.
+It is however advisable to stop the whole platform or at least make it unavailable for clients during the upgrade.
+This is to prevent malfunctions or even data inconsitencies.
+
+
+
The following upgrade procedure is the same for any service:
The server uses a Node.js clustering module but starts only one worker by default.
+It is possible to increase the number of workers in the server configuration file but this requires to modify the server.
+The preferred model to scale up is to start multiple server containers and have the reverse proxy spraying the requests on them.
+
+
+
Depending on the reverse proxy, there might be multiple strategies for the actual distribution of the load.
+A requirement for the load balancing strategy is to route requests coming from the same client to the same container (sticky sessions) for the duration of a page visit at least.
+As there is no HTTP session in Restorecommerce, the client IP address can be used as a hashing key instead.
+
+
+
One worker is enough for low-traffic sites, even in the case of up to 50 concurrent clients when ran on reasonably powerful server hardware.
Restorecommerce features an attribute based access control model (ABAC) which is heavily inspired by XACML.
+XACML is pretty complex but very powerful, which is why Restorecommerce narrows it down to a profile consisting of the essential bits and pieces for JSON driven APIs.
+We use the concepts of XACML as follows with XACML terms in italics:
+
+
+
+
+
The Subject is determined by the defined authentication service.
+
+
+
A role represents a single Policy.
+
+
+
Policies may have multiple Rules.
+
+
+
The Target of a rule consists of the resource it applies to, the performed actions and an associated scope.
+
+
+
The Effect of a rule is always Permit (white listing).
+
+
+
There is no pendant to the Condition, Advice, Obligation and Environment rule components.
+
+
+
JSON based syntax instead of XML.
+
+
+
+
+
XACML building blocks relate to Restorecommerce as follows:
+
+
+
+
+
The PIP (Policy Information Point) is the endpoint of the role resource.
+
+
+
An API is implicitly a combined PDP/ PEP (Policy Decision/ Enforcement Point).
+
+
+
The PAP (Policy Administration Point) is the API for accessing security related resources.
+
+
+
+
+
There is a single Rule type with the following Target attributes:
+
+
+
+
+
Resource IRI (res).
+
+
+
Action mask (mask) where the most permissive mask is: crud.
+
+
+
Scope (scope).
+
+
+
+
+
The rule combining algorithm is simply to permit the Authorization Request if at least one rule applies (logical or).
+If there are no matching target attributes for a request, the effect is a deny.
+
+
+
Authorization Requests corresponding to this rule type take the following form:
+
+
+
+
+
Subject attributes:
+
+
+
+
subject with an IRI as value.
+
+
+
+
+
+
Resource attributes:
+
+
+
+
resource with an IRI as value,
+
+
+
scope value as defined above.
+
+
+
+
+
+
Action attributes:
+
+
+
+
action with possible values: c, r, u, d as described above.
+
+
+
+
+
+
+
+
The scopes are evaluated with their set relationship taken into account;
+For example a request for a resource with scope user which is in fact owned by the subject and the subject is granted access to the scope app, succeeds as it includes user.
+
+
+
PAP-wise, the following is important:
+
+
+
+
+
Roles are the vehicle to delegate access rights but they are never used to make authorization decisions by solely the fact that a subject has assigned a BR.
+Only the rules in the policy of a role are considered.
+