Skip to main content
Skip table of contents

API RESTful API (v1)

The APIv1 of Opencell that have been designed did not comply with the RESTful standardization. In this page, we talk about the implementation of the RESTful standardization on the endpoints of APIv1.

RESTful standard

In the context of RESTful standardization, the APIv1 has been modified in accordance with the RESTful standard. To better understand the RESTful standard, please refer to rules in the following attached file.

Opencell_API_Governance.pptx

We will highlight several RESTful rules that we find important to be followed by our APIv1.

  • Paths are in lowercase, compound words follow camelCase naming convention. Concretely

    • If a word is composed of only one single word, its letters must be in lowercase .

    • Otherwise, if a word is composed of many single words, all letters must be in lowercase, except the first letters in each single word (except the first single word).

    • Example of words composed of one single word : seller, customers. And example of words composed of many single words : customerAccount, billingAccounts, jobInstance, usageChargeTemplates.

  • Among all CRUD endpoints, we use Read endpoint (GET request) for data retrieval, Create endpoint (POST request) for resource creation, Update endpoint (PUT request) for resource update, Delete endpoint (DELETE request) for resource suppression

  • HTTP status codes should be used for different types of request : 201 Created for resource creation, 204 No-content for resource update or resource suppression, etc.

  • Phone numbers, email, date should follow ISO standards

Available standard endpoints

Basically, the endpoints in APIv1 represent the standard HTTP Action Verbs - CRUD which stand for Create, Read, Update, and Delete :

  • GET : two endpoints allow to retrieve data (action Read) : the first one retrieves all entities, the second one retrieves a particular entity based on its code

  • POST : one endpoint allows to create a new instance of an entity (action Create)

  • PUT : one endpoint allows to update or make a particular action on an entity (action Update). The instance is retrieved based on its code

  • DELETE : one endpoint allows to delete a particular instance of an entity (action Delete). The instance is retrieved based on its code

URL redirection

By definition, URL redirection, also called URL forwarding, is a World Wide Web technique for making a web page available under more than one URL address.

Our process to apply RESTful standard on endpoints of APIv1 relies on same technique in order to make each of them available under two URLs. Concretely, a URL address respecting the RESTful standard is redirected to its corresponding URL address in APIv1.

The redirection process is handled by a HashMap which is populated at deployment, where its pair (key, value) represents a mapping between the RESTful URL address and its corresponding URL address in APIv1. An example for URL redirection is presented in the table below for all HTTP verbs CRUD applied to the entity Seller.

Let us take an example :

For the endpoint allowing to retrieve all entities of Seller, the RESTful URL address that we have proposed is as follows :

https://{host}/opencell/api/rest/v1/accountManagement/sellers

where host represents the server that we would like to query

When the server receives this query, it will be redirected to its corresponding URL in APIv1 :

https://{host}/opencell/api/rest/seller/list

Consequently, this endpoint of APIv1 is executed and returns the list of all entities seller in the database.

Paging and filtering

Similar to the Generic API, we have also added different options to make paging, to sort or to filter out a response in endpoints allowing to retrieve all entities These options could be offset, limit, sort, fields, fromRange, toRange, inList, likeCriteria, etc. The list of available options is shown in the table below. We remark that these options are added as query parameters.

Keyword

Description

offset

  • The first index is started from the value of offset

  • Syntax : "offset": 1

limit

  • Limit the number of entities that should be returned.

  • Syntax : "limit": 4

sort

  • Sort the list of entities returned.

  • Syntax : "sort": "-description,code” . This syntax means that the list of result is firstly sorted by the field description in descending order, then is sorted by the field code in ascending order

fromRange

  • Field value in between from a particular value to plus infinity.

  • Applies to number type fields.

  • Syntax : "fromRange id": 1

  • Remark that %20 is used to encode a blank space

toRange

  • Field value in between from minus infinity to a particular value.

  • Applies to number type fields

  • Syntax : "toRange id": 6

inList

  • Field value is in value (list).

  • A comma separated string will be parsed into a list if values.

  • Syntax : "inList id": [1,2,3,4,5,6]

likeCriteria

  • Multiple field names can be specified. Any of the multiple field values match the value (OR criteria).

  • In case value contains *, a like criteria match will be used.

  • In either case case insensitive matching is used.

  • Applies to String type fields.

  • Syntax : "likeCriteria description": "*Partner*" (note that the value should be placed between quotes)

ne

  • Filter a field which is not equal to something

  • Syntax: "ne id": "-3"

SQL

  • Filter based on an SQL request

  • Syntax: "SQL": "code='SELLER_FR'"

TO BE CONTINUED…

TO BE CONTINUED…

Standard format of request

The request must follow a predefined standard. In this section, we show the standard format for different requests. The available requests in APIv1 are numerous (more than 450). In the table below, we take as illustration 5 requests that permit to manipulate the entity Seller.

HTTP Verb

Request format

Query Params

Payload

Description

Response code

GET

https://{host}/opencell/api/rest/v1/accountManagement/sellers

  • limit : limit the number of entities returned

  • offset : you retrieve a subset of records starting with the offset value

  • sort : the result list will be ordered according to sort

  • fromRange : add a lower bound condition on a data field

  • toRange : add an upper bound condition on a data field

  • inList : specify whether a data field is part of a list

  • fields : specify only data fields that you wan to return

  • likeCriteria : specify a search criteria for a data field

  • etc.

none

return the list of all entities of seller based on criteria

Example :

CODE 
GET https://{host}/opencell/api/rest/v1/accountManagement/sellers
{
    "offset": 0,
    "limit": 4,
    "sort": "-description,-id",
    "filters": {
        "likeCriteria description": "*Seller*",
        "SQL": "code='SELLER_FR'",
        "inList id": [1, 2, 3, -3],
        "ne id": "-1",
        "fromRange id": -6,
        "toRange id": 0
    }
}

  • 200

  • 400

  • 404

  • 500

GET

https://{host}/opencell/api/rest/v1/accountManagement/sellers/{sellerCode}

There is no query parameters for this endpoint

There is no payload for this endpoint

return a particular of seller based on its code

Example :

CODE 
GET https://{host}/opencell/api/rest/v1/accountManagement/sellers/MAIN_SELLER

  • 200

  • 400

  • 404

  • 500

POST

https://{host}/opencell/api/rest/v1/accountManagement/sellers

There is no query parameters for this endpoint

  • In the body, we need to pass the payload (dto) that contains necessary content to create the new entity.

  • The entity below represents a dto to create an instance of seller

    JSON 
    {
	"code" : "ben.ohara.customer",
	"description" : "Seller Bestpress",
	"currencyCode" : "EUR",
	"countryCode" : "FR",
	"languageCode" : "FRA",
    "contactInformation": {
        "email": "billing@.com",
        "phone": "0123456789",
        "mobile": "0678912345",
        "fax": null
    },
    "address": {
		"address1": "52 rue Kleber",
        "address2": "",
        "address3": "",
        "zipCode": "92300",
        "city": "Levallois Perret",
        "country": "FR",
        "state": null
    }
}

create a new instance of seller

Example :

CODE 
POST https://{host}/opencell/api/rest/v1/accountManagement/sellers

  • 200

  • 400

  • 404

  • 500

PUT

https://{host}/opencell/api/rest/v1/accountManagement/sellers/{sellerCode}

There is no query parameters for this endpoint

JSON 
{
	"description" : "Partner Seller",
	"currencyCode" : "EUR",
	"countryCode" : "FR",
	"languageCode" : "FRA",
    "contactInformation": {
        "email": "billing@opencellsoft.com",
        "phone": "0123456789",
        "mobile": "0678912345",
        "fax": null
    },
    "address": {
		"address1": "52 rue Kleber",
        "address2": "",
        "address3": "",
        "zipCode": "92300",
        "city": "Levallois Perret",
        "country": "FR",
        "state": null
    }
}

update the seller instance whose code is sellerCode

Example :

CODE 
PUT https://{host}/opencell/api/rest/v1/accountManagement/sellers/MAIN_SELLER

  • 200

  • 400

  • 404

  • 500

DELETE

https://{host}/opencell/api/rest/v1/accountManagement/sellers/{sellerCode}

There is no query parameters for this endpoint

There is no query parameters for this endpoint

delete the seller instance whose code is sellerCode

Example:

CODE 
DELETE https://{host}/opencell/api/rest/v1/accountManagement/sellers/MAIN_SELLER

  • 200

  • 400

  • 404

  • 500

Standard format of response

The response of a successful request needs to follow a standard.

HTTP Verb

Response format

GET - get all entities

JSON 
{
    "actionStatus": {
        "status": "SUCCESS"
    },
    "paging": {
        "filters": {},
        "fields": "",
        "offset": ,
        "limit": ,
        "sortBy": "",
        "loadReferenceDepth":,
        ...
    },
    "{yourEntities}": [
        {
            "id": ,
            "code": "",
            "description": "",
            ...
        }
    ]
}

GET - get a particular entity

JSON 
{
    "actionStatus": {
        "status": "SUCCESS"
    },
    "{yourEntity}":
    {
        "id": ,
        "code": "",
        "description": "",
        ...
    }
}

POST

CODE 
{
    "status": "",
    "message": ""
}

PUT

JSON 
{
    "status": "",
    "message": ""
}

DELETE

CODE 
{
    "status": "",
    "message": ""
}

The response format of an unsuccessful request is also predefined as follows.

HTTP Verb

Response format

GET - get all entities

JSON 
{
    "status": "",
    "errorCode": "",
    "message": ""
}

GET - get a particular entity

JSON 
{
    "status": "",
    "errorCode": "",
    "message": ""
}

POST

CODE 
{
    "status": "",
    "errorCode": "",
    "message": ""
}

PUT

JSON 
{
    "status": "",
    "errorCode": "",
    "message": ""
}

DELETE

CODE 
{
    "status": "",
    "errorCode": "",
    "message": ""
}

Where :

  • status defines the status of the request (SUCCESS, FAIL, etc.)

  • errorCode defines the error code associating to the failure of the request

  • message gives detailed information about the failure (i.e., entity with the code does not exist)

Documentation

We have here two different ways to get the list of REST API endpoints in Opencell.

  • We have created two new endpoints GET permitting to retrieve all endpoints that have been already handled to respect RESTful standard.

The first endpoint allows to get all endpoints :

https://{{host}}/opencell/api/rest/v1/restEndpoints

The second endpoint allows to get endpoints of an entity :

https://{{host}}/opencell/api/rest/v1/restEndpoints/{{entityName}}

  • OpenAPI documentation is available directly on your Opencell instance:

    • https://{{host}}/opencell/pages/docs/v1 (in a Swagger viewer)

    • https://{{host}}/opencell/api/rest/v1/openapi.json (direct link to OpenApi document)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close