API design style guide

This chapter introduces methods in APIJSON. These methods are:

GET

It provides a general way to retrieve resources.

HEAD

It provides a general way to count resources satisfying specifics in the request body.

GETS

It requests for highly secured and confidential data like bank accounts, birth dates.

HEADS

It’s used for getting counts of highly secured resources(eg. bank accounts).

POST

It creates new resources under the specified parent resource(TableName).

PUT

This method asks the server to update/edit an existing resource.

DELETE

This method deletes the specified resource.

Request method tells the server what kind of action the client wants the server to take. The method are also commonly referred to as the request “verb”. This chapter will show you how these methods are included in url to send requests.

In the following explanations, the base_URL means the root URL. Everything that follows it is known as a URL path. All URL paths are relative to the base URL.

1. APIJSON Methods

GET :

A general way to retrieve resources.

base_url/get/

Request

 {
  "TableName"{
  // conditions
  }
 }

// eg. Request a post with id = 235 in table "Post":
 {
  "Post"{
  "id": 235
   }
  }

Response

 {
  "TableName":{
  ...
  },
  "code":200,
  "msg":”success”
  }

// eg. The returned response:
{
 "Moment":{
 "id":235,
 "userId":38710,
 "content":"..."
  },
 "code":200,
 "msg":"success"
}

GETS :

Request for highly secured and confidential data like bank accounts, birth dates.

base_url/gets/

Request

// You need to nest a key-value pair

“tag”: tag

// at the top level of the request json object. The tag is usually the related table's name.

//Except that, the structure is the same as **GET**.

Response

// Same as **GET**

HEADS :

It’s used for getting counts of highly secured resources(eg. bank accounts).

base_url/heads/

Request

// You need to nest a key-value pair

 “tag”: tag

// at the top level of the request json object.

//Except that, the structure is the same as **HEAD**.

Response

//  Same as **HEAD**.

POST :

The POST method creates new resources under the specified parent resource(TableName).

base_url/post/

Request

{
"TableName":{…
},
"tag":tag
}

// Note the id in the object "TableName":{...} has been generated automatically when table is built and can’t be set by the user here.

// eg. A user with id = 38710 posts a new post：

{
   "Post":{
     "userId":38710,
     "content":"APIJSON lets interfaces and documents go hell!"
    },
   "tag":"Moment"
}

Response

  {
   "Moment":{
     "code":200,
     "msg":"success",
     "id":...
   },
   "code":200,
   "msg":"success"
  }

// If the request is successful, it should return following object.

  {
     TableName:{
       "code":200,
       "msg":"success",
       "id":38710
     },
     "code":200,
     "msg":"success"
  }

PUT :

The PUT method asks the server to update/edit an existing resource. The part that will be modified is included in the request body.

base_url/put/

Request

 {
    "TableName":{
      "id":id,
      …
    },
    "tag":tag
 }

 // You need to either specify the id in the TableName object like the example above or add a id{} object in the request body.

// The following example makes request to update the content made by id = 235:

 {
    "Post":{
      "id":235,
      "content":"APIJSON lets interfaces and documents go hell !"
    },
    "tag":"Post"
 }

Response

\\ Same as **POST**.

DELETE :

The DELETE method deletes the specified resource.

base_url/delete/

Request

{
   TableName:{
     "id":id
   },
   "tag":tag
}
// You need to either specify the id in the TableName object like the example above or add a id{} object in the request body.

// The following example send a request to delete comments made by id = 100,110,120

{
   "Comment":{
     "id{}":[100,110,120]
   },
   "tag":"Comment[]"
}

Response

 {
  "TableName":{
    "code":200,
    "msg":"success",
    "id[]":[...]
    "count":3
  },
  "code":200,
  "msg":"success"
 }

 // The response to the request in the example above

 {
 "Comment":{
 "code":200,
 "msg":"success",
 "id[]":[100,110,120],
 "count":3
 },
 "code":200,
"msg":"success"
 }

Note:

  1. TableName means the name of the table that a user interacts with. It’s a string with the first letter capitalized. It can be any combination of letters, numbers and underscores. As a key, its value is a jsonObject which may include columns’ names in the table.

  2. “tag”:tag needs to be included when the request method is neither GET nor HEAD. The value tag is the key of the returned jsonObject in the response body. Usually, it’s the name of the related table.

  3. The request form under GET and HEAD methods are very flexible. The request jsonObject can be nested many levels. However, other methods need to be constrained by adding tags, etc. The structure of the request body needs to conform resources at the backend.

  4. GETS and GET, HEADS and HEAD are the same type of operation. For both groups, the request bodies have something different, while the response bodies are the same.

  5. When transmit through HTTP protocal, all the API methods (get,gets,head,heads,post,put,delete) use HTTP POST verb.

  6. All jsonObjects are seen as variables or folders with the form of {...}. It can store objects or associative arrays.

  7. Each object is related to an individually-addressable resource which has an unique address.

2. Functional Key-Value Pairs

Get data in an array: /get/{"key[]":{"tableName":{}}}

The part after the colon is a JSONObject. The key is optional. When key is as the same as the tableName, the JSONObject will be in a simplified form. For example: {"User[]":{"User":{"id",...}}} will be written as {"User[]":{"id",...}}.

Example

/get/{“User[]”:{“count”:3,”User”:{}}}

In this example, the request is to GET 3 users’ information. The response includes 3 users information with all categories saved in an array.

Get filtered data: /get/{"key[]":{"tableName":{"key2{}":[]}}}

Specifically in this part: "key2{}":[], the part after the colon is a JSONArray which contains key2’s values. This part is to specify the conditions that the return should satisfy.

Example

/get/{“User[]”:{“count”:3,”User”:{“id{}”:[38710,82001,70793]}}}

This example shows how to get users’s information with id equals 38710,82001,70793.

Get data with comparison operation： /get/{"key[]":{"tableName":{"id{}":"<=80000,>90000"}}}

Just as the comparison operation functions in SQL, it’s used here to get resources in a range. It dosn’t need to be numbers though.

Example

/get/{“User[]”:{“count”:3,”User”:{“id{}”:”<=80000,>90000”}}}

In SQL, it’d be id<=80000 OR id>90000, which means get User array with id<=80000 | id>90000

Get data that contains an element: /get/{"key[]":{"User":{"key2<>":[object]}}}

This also used when the user wants to get data that meets specific conditions. key2 must be a JSONArray while object cannot be JSON.

Example

“/get/{“User[]”:{“count”:3,”User”:{“contactIdList<>”:38710}}}”:38710

In this example, it requests 3 User arrays whose contactIdList contains 38710. In SQL, this would be json_contains(contactIdList,38710).

See if it exists /get/{"key":{"key2}{@":{"from":"tableName","tableName":{...}}}}

In this request url, }{ means EXISTS; key2 is the item you want to check.

Example

`{“User”:
{“id}{@”:{

“from”:”Comment”, “Comment”:{“momentId”:15} } } } <http://apijson.cn:8080/get/%7B%22User%22:%7B%22id%7D%7B@%22:%7B%22from%22:%22Comment%22,%22Comment%22:%7B%22momentId%22:15%7D%7D%7D%7D>`_

In this example, the request is to check if the id whose momentId = 15 exists. The SQL form would be WHERE EXISTS(SELECT * FROM Comment WHERE momentId=15)

Include functions in url parameters /get/{"Table":{"key":value, key()":"function (key0,key1...)}"

This will trigger the back-end function(JSONObject request, String key0, String key1…)to get or testify data.

Use - and + to show the order of priority: analyze key-() > analyze the current object > analyze key() > analyze child object > analyze key+()

Example

/get/{“Moment”:{“id”:301,”isPraised()”:”isContain(praiseUserIdList,userId)”}}

This will use function boolean isContain(JSONObject request, String array, String value). In this case, client will get “is praised”: true (In this case, client use function to testify if a user clicked ‘like’ button for a post.)

Refer a value

"key@":"key0/key1/.../refKey"

Use forward slash to show the path. The part before the colon is the key that wants to refer. The path after the colon starts with the parent level of the key.

Example

`”Moment”:{

“userId”:38710 },

“User”:{

“id@”:”/Moment/userId” } <http://apijson.cn:8080/get/%7B%22User%22:%7B%22id@%22:%7B%22from%22:%22Comment%22,%22Comment%22:%7B%22@column%22:%22min(userId)%22%7D%7D%7D%7D>`_

In this example, the value of id in User refer to the userId in Moment, which means User.id = Moment.userId. After the request is sent, "id@":"/Moment/userId" will be "id":38710.

Subquery expression

"key@":{
    "range": "ALL",
    "from":"Table",
    "Table":{ ... }
}

Range can be ALL, ANY. It means which table you want to query. It’s very similar to how you query in SQL. You can also use COUNT, JOIN, etc.

Example

`”id@”:{

“from”:”Comment”, “Comment”:{ “@column”:”min(userId)”

}

} <http://apijson.cn:8080/get/%7B%22User%22:%7B%22id@%22:%7B%22from%22:%22Comment%22,%22Comment%22:%7B%22@column%22:%22min(userId)%22%7D%7D%7D%7D>`_

code

WHERE id=(SELECT min(userId) FROM Comment)

Fuzzy matching "key$":"SQL search expressions" => "key$":["SQL search expressions"]

Any SQL search expression can be applied here.

Example

“name$”:”%m%”

In SQL, it’s name LIKE '%m%', meaning that get User with ‘m’ in name.

Regular Expression "key~":"regular expression" => "key~":["regular expression"]

It can be any regular expressions. Advanced search is applicable.

Example

“name~”:”^[0-9]+$”

In SQL, it’s name REGEXP '^[0-9]+$'.

Get data in a range "key%":"start,end" => "key%":["start,end"]

The data type of start and end can only be either Boolean, Number or String. Eg. “2017-01-01,2019-01-01”, [“1,90000”, “82001,100000”]. It’s used for getting data from a specific time range.

Example

“date%”:”2017-10-01,2018-10-01”

In SQL, it’s date BETWEEN '2017-10-01' AND '2018-10-01', meaning to get User data that registered between 2017-10-01 and 2018-10-01.

Make an alias "name:alias"

This changes name to alias in returning results. It’s applicable to column, tableName, SQL Functions, etc. but only in GET, HEAD requests.

Example

/get/{“Comment”:{“@column”:”id,toId:parentId”,”id”:51}}

In SQL, it’s toId AS parentId. It’ll return parentID instead of toID.

Add / expand an item "key+":number/string/array...

The type of value on the right of the colon is decided by key. Types can be Number (such as 82001), String (such as “url0”), JSONArray (such as [“url0”,”url1”]). The method can only be PUT.

Example

code

“praiseUserIdList+”:[82001]

In this example, add id 82001 to the praiser’s list. In SQL, it should be json_insert(praiseUserIdList,82001).

Delete / decrease an item “Key-”:number/string/array...

It has the contrary function of “key+”.

Example

"balance-":100.00

This example subtract 100 in the balance. In SQL, it would be balance = balance - 100.00.

Logical Operators &,|,!

&,|,! refer to AND, OR, NOT in SQL respectively. The basic form to use them are: "key&{}":"conditions", "key|{}":"conditions", "key!{}":Object.

By default, conditions of the same key are connected with | operator. As for different "key":"conditons"`pairs, the default operator among them is :code:`&.

Example

① /head/{“User”:{“id&{}”:”>80000,<=90000”}}

In SQL, it’s id>80000 AND id<=90000, meaning id needs to be id>80000 & id<=90000

② /head/{“User”:{“id|{}”:”>90000,<=80000”}}.

It’s the same as "id{}":">90000,<=80000". In SQL, it’s id>80000 OR id<=90000, meaning that id needs to be id>90000 | id<=80000.

③ /head/{“User”:{“id!{}”:[82001,38710]}}.

In SQL, it’s id NOT IN(82001,38710), meaning id needs to be ! (id=82001 | id=38710).

3. Build-in string functions part one

① "count":Integer

This is used to set the maximum number of the returning resources. The maximum number the system supports is 100. Without this, it’ll return the maximum number of results that meet the condition.

Example

/get/{“[]”:{“count”:5,”User”:{}}}

This example requests 5 Users’ data.

② "page":Integer

This is to indicate the page number starting with 0. The max number can be 100. It’s usually used with "count":Integer

Example

/get/{“[]”:{“count”:5,”page”:3,”User”:{}}}

This example get Users data on page 3 with the total number of 5.

③ "query":Integer

When the Integer is 0, it means get the resource. When it’s 1, it means counting the number and returning the number.When it’s 2, it means returning both.

Example

④ "join":"&/Table0/key0@,</Table1/key1@"

The joining table functions are represented by symbols:

“<” - LEFT JOIN

“>” - RIGHT JOIN

“&” - INNER JOIN

“|” - FULL JOIN

“!” - OUTTER JOIN

Example

4. Build-in string functions part two

① "@combine":"&key0,&key1,|key2,key3,!key4,!key5,&key6,key7..."

This function combines conditions that have been listed to request data. It’ll group conditions according to their types. It uses logical operators(&,|,!) to connect among groups while within a group, it’ll follow the order that conditions have been listed. So, it’ll become :code:`(key0 & key1 & key6 & other keys) & (key2 | key3 | key7) & !(key4 | key5) `

The:code:other keys means keys that aren’t included in combine function. By default, it’s connected by AND.

Example

② "@column":"column;function(arg)..."

This function defines which colunms will be returned.

Example

/get/{“User”:{“@column”:”id,sex,name”,”id”:38710}}

This request only returns colunms: id, sex, name. The returning follows the same order.

③ "@order":"column0+,column1-..."

This function can set descendent or ascendent order of returning data within a column.

Example

/get/{“[]”:{“count”:10,”User”:{“@column”:”name,id”,”@order”:”name-,id”}}}

This example requests data following descendent order in name column while the default order in id column.

④ "@group":"column0,column1..."

This function groups data with columns. If the table’s id has been declared in @column, then the id needs to be included in @group.

Example

⑤ "@having":"function0(...)?value0;function1(...)?value1;function2(...)?value2..."

This function is as same as the HAVING function in AQL. Normally, it’s used with @group.

Example

/get/{“[]”:{“Moment”:{“@column”:”userId;max(id)”,”@group”:”userId”,”@having”:”max(id)>=100”}}}

This example get an array of Moment with userID and id where id >=100, grouped by userId.

⑥ "@schema":"sys"