Overview

Introduction

The N-Squared Flow Editor provides a RESTful HTTP API using JSON for data content transfer. The API is accessed at the following endpoint:

https://n2fe.host/jarvis-agent/n2fe/

or

https://n2fe.host/n2fe/jarvis-agent/n2fe/

The second form is useful for reverse proxies which require a single base path for all access points into N2FE.

The host (n2fe.host in this example) is the IP or hostname where the Flow Editor’s web services interface is installed. Depending on site setup, either http or https may be used.

Generally this API documentation will refer to the API endpoint from this base URL.

For example the following API call would provide information on the currently logged in user for a flow editor setup on the local host:

curl http://localhost/jarvis-agent/n2fe/__status

The following request would (with appropriate content in flow.json) create a new flow in the underlying OCNCC instance via the flow editor web services API:

curl 'http://localhost/jarvis-agent/n2fe/api/flow/221389' -H 'Content-Type: application/json;charset=utf-8' \
     -T flow.json -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

HTTP Verbs

As a generally RESTful interface, the HTTP API uses HTTP method types to indicate actions. The following mapping is employed:

Method Meaning
GET Retrieve data, either single objects or arrays of objects matching criteria provided in the URL.
POST Insert new records.
PUT Update existing records.
DELETE Delete existing records.

URL Format

URLs are used to identify the type of resource to retrieve. Special URLs for login, logout and status retrieval of the currently authenticated user are available:

curl 'http://localhost/jarvis-agent/n2fe/__login?username=bob&password=thebuilder'
curl 'http://localhost/jarvis-agent/n2fe/__status' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'
curl 'http://localhost/jarvis-agent/n2fe/__logout' -H 'Cookie: N2FE_CGISESSID=48ac880f98504e81373207d62dd2f807'

Access to application resources such as Customers, Flows and Holiday Sets are via resource URLs with embedded IDs identifying the resource to retrieve. For example the ID:

curl 'http://localhost/jarvis-agent/n2fe/api/flow/221389'

Includes the ID 221389 which identifies the flow resource to get.

URL parameters are used for filtering and limiting the results returned.

Sorting and Paging Results

Where noted, API requests which may return a significant number of records in a response are designed to “page” their results on the server. Responses designed with server-side paging will limit the number of returned records, and requests must include explicit paging parameters to retrieve the specific page required.

Paging parameters:

Parameter Default Description
page_start 0 The record number to start at for records from the server to return. The first record from the server’s record list will be record number page_start (i.e. this isn’t a page number, but a record number). The value of page_start must always be non-negative.
page_limit 25 The maximum number of records to return. Less may be returned if the server’s record count is less than page_start + page_limit. The value of page_limit must always be greater than zero. For practical reasons a maximum limit is internally applied on each API supporting server-side paging as well.

Paging successfully requires a consistent sort to be applied between HTTP calls made with different paging parameters. It is not effective for server-side paging to be performed with client side sorting.

To support record sorting, server-side paging requires server-side sorting. Where API requests support client-determined server side sorting, the following parameters can be used to determine the sorting to be applied:

Parameter Default Description
sort_field none The field name to sort on. Each API has a different natural sorting which will be used by default. The possible values of sort_field depend also on the API being called.
sort_dir ASC The sort direction, either ascending or descending. By default sorting is ascending.

Effective visual representatations of data with server-side paging requires knowledge of the total number of records available. To provide this data to the client, the following headers are provided:

Header Description
X-Query-Count The total number of records which match the request without considering the page-size.

HTTP Headers

Generally the client may send any HTTP headers they wish - they are not directly used by the flow editor web services in most cases, however as the HTTP API is run through Apache HTTP appropriate headers for compression may be used.

The following HTTP headers however are critical for the HTTP API:

Header Description
Cookie The HTTP cookie whose name matches the sid_param provided on successful login is used to authorize the request. All requests after the login request must include this cookie otherwise the request will not be honored.
Content-Type For all POST and PUT requests (i.e. all update requests) other than the long request, the content type must be set to application/json;charset=utf-8 to ensure that the POST/PUT body is parsed correctly as JSON rather than HTTP parameters.

Security

Jarvis may be configured with XSRF and CSRF protection, and also cross site origin protection. If these protections are enabled, some general rules apply to using the API beyond that which is shown in these documents.

  1. If XSRF protection is enabled, all JSON responses from the server will be prefixed with )]}',\n". This must be stripped by the client before interpreting the result.

  2. If CSRF protection is enabled, the HTTP cookie provided to the client with the CSRF token (by default this is XSRF_TOKEN) must have it’s content copied into the CSRF header (the default header is X-XSRF-TOKEN) for each request.

  3. If Cross site origin protection is enabled, a referrer header must be correctly provided to the server.