1 Intro

Source: This article refers to 1 Intro

1.1 Overview

The Coresystems API is an easy, yet powerful mechanism which provides full access to the data stored on the Coresystems Cloud. Data is represented in form of more than 100 domain objects. Beside simple Create, Read, Update and Delete operations, the user is able to perform complex data queries with optional filtering, expanding of linked objects, partial object fields retrieval, pagination and ordering.

The access to the data is restricted by authentication and authorization mechanism which ensures that the data can be accessed by authorized persons only. On top of that all communications between the API client and API server is encoded with SSL.

The API is based on RESTful approach for web services and uses JSON format for object representation.

Please check reference and data model sections for more information

In order to use Coresystems API the developer needs to be aware of main components which the cloud server consists of. There are two types of the cloud server nodes which serve different purposes:

  • Master Server Node - hosts meta information need for authentication, authorization and Data Server Node location.
  • Data Server Node - hosts actual company data. Normally, when the client application is launched for the first time it queries a Master Server Node service toretrieve information about the Data Server Node where the company data is stored. Having this location informationcached (or stored) the client application connects to the given Data Server Node in order to perform CRUD operationson the company data. The Master and Data Server Node services are described in the Reference section.

1.2 Domain Model

The domain model is actually made up of current Data Transfer Objects (DTOs). Given the fact that the API supports “expand” queries, the clients can choose exactly what they want to get from the cloud. Please, note that Resource/Field names used in the url are case sensitive. The convention is to use camel case naming with uppercase first letter for resources (e.g. ServiceCall) and lowercase first letter for fields (e.g. createPerson).


1.3 Authentication

Note: Coresystems uses OAuth 2.0 for authorization. For more information on OAuth 2.0, including information, refer to the following topic.

To authenticate a request, the client have to send the credentials as HTTP query string parameters to the server:

Query String Parameter Description
accountName cloud account name
companyName cloud company name
userAccountName cloud user account name
userAccountPasswordHash user cloud account password SHA-512 hash
clientIdentifier client application identifier (e.g. COR_MOBILE_IPHONE)

1.4 Authorization

User authorization is based on permissions which specify what CRUD actions are available for a user making an API call. The permission system in the cloud consists of a set of rights and attributes defined on the available DTOs. The set specifies which users are granted access to objects, as well as what operations are allowed on a given object type. Additionally each permission entry can contain a list of custom permissions used by the client application.

There are four basic types of operations allowed on business object: Create, Read, Update, Delete (CRUD). Each permission entry defines which of those are applicable on a given object type, and what is the minimum relation required between the object and user.

Relation Description
NONE The CRUD operation can't be performed on this business object type
OWN The CRUD operation can be performed on this business object only if it is 'owned' by the user
ALL The CRUD operation can be performed on any business object of given type

Meaning of OWN can be different for different business object type. Usually the user has to be one of create persons, but some object types have other requirements.

1.4.1 Effective Permissions

Effective permissions are calculated using default permissions and user permissions.

If user has two or more subscriptions assigned, then the sets of default permission values are summed. For the permission value, the highest one is taken.

After calculating the effective default permissions, user defined permissions are applied on top of them.


1.5 Data Formats

Resources in the Coresystems API are represented using JSON data format.

1.5.1 Supported Data Types

Type name
Description
bool A boolean value
int Four byte signed integer
long Eight byte signed long
double Eight byte signed floating point number.
string An UTF-8 string with a maximum length of 2'000'000 bytes.
guid A GUID is a identifier string which is 16 characters wide. It uniquely identifies a object in the cloud.
date Date only value without time and time zone information. No time zone adjustments should be done on client side.
dateTime A combined data type which contains a date and a time zone. The DateTime values comply with ISO8601 format representation.
objectref An aggregate data type. Consists of guid of an object and a string - its object type.
Both values must be set to be valid. For objectref the guid AND the objecttype must be set. objecttype contains a domain object name in capital letters i.e. "BUSINESSPARTNER", "ADDRESS", ...
dictionary<Key, Value> A dictionary. Key and Value are data types (could be different).

1.6 Versioning

All API calls should be versioned using the following convention: https://www.baseurl.com/api/data/{v4}/…. Where {v4} represents the version of the API call that is being made. First version will be identified by v4 as a successor of the latest Data API V3, subsequent versions will follow the convention v5, v6, … vn

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.