Skip to content

RESTful Endpoints

Jump to bottom
VinceZK edited this page Apr 4, 2020 · 10 revisions

All active RESTful endpoints can be found in ./server/routes.js. This page gives documentation and examples to each endpoint.

All the endpoints share the same error handling. When error(s) happens, error(s) will be returned in following JSON format(just an example):

[ 
  { msgCat: 'GENERAL', msgName: 'GENERAL_ERROR', msgType: 'E', 
    msgShortText: 'Error happened', msgLongText: 'Error happened', showLongText: false }
]

Create an instance

The input JSON should be a correct representation of an given entity, which means:

  1. It must have a valid 'ENTITY_ID';
  2. No 'INSTANCE_GUID' is given, as it will be given by JOR and returned when successfully created;
  3. All mandatory Relations(with cardinality equals '[1..1]' or '[1..n]') are given;
  4. If Relationship is given, the partner instance should be valid;
  5. A lot of other checks, like foreign key, relation validity, relationship validity, primary key missing, and so on.

If any error happened, the instance will not be saved in DB, and error messages will be returned. Otherwise, the return is then JSON of the instance with INSTANCE_GUID.

Example:

POST http://localhost:3000/api/entity
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{ "ENTITY_ID": "person",
  "person": {"HEIGHT": "180", "GENDER": "male", "HOBBY":"Reading, Movie, Coding", "TYPE": "employee", "SYSTEM_ACCESS": "portal"},
  "r_user": {"USER_ID": "DH999", "USER_NAME":"John", "DISPLAY_NAME": "John Wu"},
  "r_email": [{"EMAIL": "dh999@hotmail.com", "TYPE": "private", "PRIMARY":1}],
  "r_employee": {"USER_ID": "DH999", "COMPANY_ID":"Darkhouse", "DEPARTMENT_ID":"Development","TITLE":"Developer"},
  "relationships":[
    { "RELATIONSHIP_ID": "rs_user_role",
      "values":[
        { "SYNCED":0,
          "PARTNER_INSTANCES":[
            {"ENTITY_ID":"system_role", "ROLE_ID":"system_role", "INSTANCE_GUID":"5F50DE92743683E1ED7F964E5B9F6167"}]}
      ]
    }]
}

Change an instance

The given JSON contains the attributes that are required for change, as well as those primary key attributes which are used for identifying a tuple. Both ENTITY_ID and INSTANCE_ID must be given. The reserved field "action" is introduced for each relation tuple. Its value could be one of the following: "update", "add", and "delete".

If any error happened, the change will not be saved in DB, and error messages will be returned. Otherwise, no error message means success.

The example below will do the following changes:

  1. Update the HEIGHT and HOBBY of "person" relation;
  2. Update the USER_NAME of "r_user" relation;
  3. Add a new email address;
  4. Add a new relationship to "system_role".
PUT http://localhost:3001/api/entity
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{ "ENTITY_ID": "person",
  "INSTANCE_GUID": "2FBE7490E10F11E8A90957FA46F2CECA",
  "person": {"action": "update", "HEIGHT": 180, "HOBBY":"Reading, Movie"},
  "r_user": {"action": "update", "USER_ID": "DH999", "USER_NAME":"JohnWu"},
  "r_email": [{"action": "add", "EMAIL": "dh999@darkhouse.com", "TYPE": "work", "PRIMARY":0}],
  "relationships":[
    {
      "RELATIONSHIP_ID": "rs_user_role",
      "values": [
        {
          "action": "add",
          "VALID_FROM": "2020-12-31 00:00:00",
          "VALID_TO": "2030-12-31 00:00:00",
          "SYNCED": 1,
          "PARTNER_INSTANCES": [
            {
              "ENTITY_ID": "system_role",
              "ROLE_ID": "system_role",
              "INSTANCE_GUID": "F914BC7E2BD65D42A0B17FBEAD8E1AF2"
            }
          ]
        }
      ]
    }]
}

Overwrite an instance

The API overwrites an instance as a whole with a given JSON object. Those appeared relations are updated with new values. Those not appeared will be deleted. This API is useful in some UI technologies which always regards an entity as a whole. Then you don't have to trace every changed pieces, just post it as an atomic object to the backend store.

Besides it may introduce some performance overhead, another limitation is that relationships are not supported with "overwrite" mode. This is because a relationship always deals with more than 2 entities, thus cannot be overwritten from one single side.

PUT http://localhost:3001/api/entity/overwrite
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{ "ENTITY_ID": "person",
  "INSTANCE_GUID": "2FBE7490E10F11E8A90957FA46F2CECA", 
  "person": {"HEIGHT": "180", "GENDER": "male", "HOBBY":"Reading, Movie, Coding, Singing"},
  "r_user": {"USER_ID": "DH999", "USER_NAME":"JohnWu", "DISPLAY_NAME": "John Wu"},
  "r_email": [{"EMAIL": "dh999@hotmail.com", "TYPE": "private", "PRIMARY":1}],
  "r_employee": {"USER_ID": "DH999", "COMPANY_ID":"Darkhouse", "DEPARTMENT_ID":"Development","TITLE":"Developer"}
}

Get an entity instance through its UUID

The return is an entity instance in JSON format. The relationships are also included

GET http://localhost:3001/api/entity/instance/2FBE7490E10F11E8A90957FA46F2CECA
Accept: */*
Cache-Control: no-cache

Get pieces of an entity instance through its UUID

Use this API to decide which relations or relationships you need from an entity instance. The given example requests 2 relations: "r_user" and "r_email" from a person entity, together with one relationship "rs_user_role". The return is a projection of the entity instance.

The API can save performance if you only need some pieces of the information from a big entity.

POST http://localhost:3001/api/entity/instance/piece/2FBE7490E10F11E8A90957FA46F2CECA
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{
  "RELATIONS": ["r_user", "r_email"],
  "RELATIONSHIPS": ["rs_user_role"]
 }

Get an entity instance through one of its business ID

The business ID always belongs to one of an entity's relations. For example, the attribute USER_ID is one of the person entity's business IDs, which belongs to the relation "r_employee". You need to make sure the business ID can uniquely identify the entity, or it will give you the first hit that matches this ID.

The return is a complete entity instance in JSON format.

POST http://localhost:3001/api/entity/instance
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{
  "RELATION_ID": "r_employee",
  "USER_ID": "DH001"
}

Get pieces of an entity instance through its business ID

Use this API to get pieces of an entity from its business ID. In following example, it gets relations "r_user" and "r_email", and the relationship "rs_user_role" for the user "DH001".

POST http://localhost:3000/api/entity/instance/piece
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{
  "ID": {
    "RELATION_ID": "r_user",
    "USER_ID": "DH001"
  },
  "piece": {
    "RELATIONS": ["r_user", "r_email"],
    "RELATIONSHIPS": ["rs_user_role"]
  }
}

Get partner information from the relationship

When you make a request to retrieve the information of an entity, you also want some of its partners' information. You don't need to make 2 or more requests, just request the partners' information in the relationships.

Like bellow request, it will return the role and marriage partner information together with the person's own information. You can recursively request all the entities that have relationship networks with each other.

POST http://localhost:3000/api/entity/instance/piece
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{
  "ID": {
    "RELATION_ID": "r_user",
    "USER_ID": "DH001"
  },
  "piece": {
    "RELATIONS": ["r_user", "r_personalization"],
    "RELATIONSHIPS": [
      {"RELATIONSHIP_ID": "rs_user_role",
       "PARTNER_ENTITY_PIECES": [
        {"ENTITY_ID": "permission",
         "piece": {"RELATIONS": ["r_role"], "RELATIONSHIPS": ["rs_user_role"]}}]},
      {"RELATIONSHIP_ID": "rs_marriage",
       "PARTNER_ENTITY_PIECES": [
         {"ENTITY_ID": "person",
           "piece": {"RELATIONS": ["person"]}}]}
    ]
  }
}

Generic Query Request

A query is defined as a JSON object with 2 mandatory attributes: "ENTITY_ID" and "RELATION_ID". You must tell the system on which entity and which leading relation the query is made on.

"PROJECTION" is an array in which you can include fields not only from the leading relation, but also from all the associated relations. The system helps you to do the sql-joins. If "PROJECTION" is not given, then it means all the fields from the leading relation.

The filter is limited with operators: EQ(Equal), NE(Not Equal), GT(Greater Than), GE(Greater than and Equal), LT(Less Than), LE(Less Than and Equal), and BT(Between). You can also use fields from the assoicated relations to do the filtering and sorting.

You can also define sort criteria. On which which fields you want to sort the result sets, ascending(asc) or descending(desc). The return is a list of entries that fulfills the query.

POST http://localhost:3001/api/query
Accept: */*
Cache-Control: no-cache
Content-Type: application/json

{
  "ENTITY_ID": "person",
  "RELATION_ID": "r_user",
  "PROJECTION": [
    "USER_ID",
    "USER_NAME",
    "GIVEN_NAME",
    {"FIELD_NAME": "COMPANY_ID", "ALIAS": "Company", "RELATION_ID": "r_employee"}
  ],
  "FILTER": [
    {
      "FIELD_NAME": "USER_ID",
      "OPERATOR": "BT",
      "LOW": "DH001",
      "HIGH": "DH999"
    },
    {
      "FIELD_NAME": "LANGUAGE",
      "OPERATOR": "EQ",
      "RELATION_ID": "r_personalization",
      "LOW": "ZH"
    }
  ],
  "SORT": [
    {
      "FIELD_NAME": "LANGUAGE",
      "RELATION_ID": "r_personalization",
      "ORDER": "desc"
    }
  ]
}

Clone this wiki locally