apijson docs - read the docs
TRANSCRIPT
APIJSON DocsRelease 100
Ruoran Wang
Jan 17 2020
QUICK START
1 About APIJSON 1
2 Features 3
3 Server-side Deployment 7
4 Client-side Deployment 11
5 API design style guide 13
6 What APIJSON has achieved 25
7 Indices and tables 27
i
ii
CHAPTER
ONE
ABOUT APIJSON
APIJSON is a JSON based internet communication protocol exclusively for API design and an ORMlibrary based on this protocal APIJSON can largely simplifies the process of API development It helpsdevelopers to build an automatic API with functions like CRUD data search
By saving communication time between front-end and back-end developers and hours of API developmentwork it largely reduces costs of API development
APIJSON is recommanded to small to medium web applications that have decoupled front and back endssuch as startup company projects or company internal use projects
APIJSON has been honored by Gitee as the Most Valuable Project in 2019
1
APIJSON Docs Release 100
2 Chapter 1 About APIJSON
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
QUICK START
1 About APIJSON 1
2 Features 3
3 Server-side Deployment 7
4 Client-side Deployment 11
5 API design style guide 13
6 What APIJSON has achieved 25
7 Indices and tables 27
i
ii
CHAPTER
ONE
ABOUT APIJSON
APIJSON is a JSON based internet communication protocol exclusively for API design and an ORMlibrary based on this protocal APIJSON can largely simplifies the process of API development It helpsdevelopers to build an automatic API with functions like CRUD data search
By saving communication time between front-end and back-end developers and hours of API developmentwork it largely reduces costs of API development
APIJSON is recommanded to small to medium web applications that have decoupled front and back endssuch as startup company projects or company internal use projects
APIJSON has been honored by Gitee as the Most Valuable Project in 2019
1
APIJSON Docs Release 100
2 Chapter 1 About APIJSON
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
ii
CHAPTER
ONE
ABOUT APIJSON
APIJSON is a JSON based internet communication protocol exclusively for API design and an ORMlibrary based on this protocal APIJSON can largely simplifies the process of API development It helpsdevelopers to build an automatic API with functions like CRUD data search
By saving communication time between front-end and back-end developers and hours of API developmentwork it largely reduces costs of API development
APIJSON is recommanded to small to medium web applications that have decoupled front and back endssuch as startup company projects or company internal use projects
APIJSON has been honored by Gitee as the Most Valuable Project in 2019
1
APIJSON Docs Release 100
2 Chapter 1 About APIJSON
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
ONE
ABOUT APIJSON
APIJSON is a JSON based internet communication protocol exclusively for API design and an ORMlibrary based on this protocal APIJSON can largely simplifies the process of API development It helpsdevelopers to build an automatic API with functions like CRUD data search
By saving communication time between front-end and back-end developers and hours of API developmentwork it largely reduces costs of API development
APIJSON is recommanded to small to medium web applications that have decoupled front and back endssuch as startup company projects or company internal use projects
APIJSON has been honored by Gitee as the Most Valuable Project in 2019
1
APIJSON Docs Release 100
2 Chapter 1 About APIJSON
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
2 Chapter 1 About APIJSON
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
TWO
FEATURES
For API developers
bull APIJSON largely reduces API developersrsquo workload by reducing most API protocals design work and docu-mentation work
bull APIJSON supports automatic permission verification version management and SQL injection prevention TheAPI has no version so developers no longer need to worry about the update of API protocals or the derivativedocumentation update
bull With these features it saves communication time between front-end and back-end developers about the APIdesign
For users
bull You can get many resources and different forms of data by making just a single request While typical RESTAPIs require loading from multiple URLs Being convenient and flexible it saves sending multiple requestswith multiple API endpoints
bull It provides CRUD(read and write) Fuzzy Search Remote Method Invocation (RMI) etc Other features includesaving duplicate data checking request history etc
21 Examples
APIJSON is organized by json objects not endpoints The client can access full capabilities of the data from a singleendpoint To send a request the basic structure is
baseURL Methods(GETGETSPOSTetc) JSONObject query
The following example shows how to query a userrsquos information
Get a user
Request
User
Response
Userid38710sex0
(continues on next page)
3
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
(continued from previous page)
nameTommyLemoncertifiedtruetagAndroidampJavaphone13000038710headhttpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000
rarr˓date1485948110000pictureList[httpstaticoschinanetuploadsuser12182437072_100jpgt=1461076033000httpcommoncnblogscomimagesicon_weibo_24png
]code200msgsuccess
Try it yourself
The following example shows the query of getting three usersrsquo id and name
Get an array of users
Request
[]count3User
columnidname
Response
[][
Userid38710nameTommyLemon
Userid70793nameStrong
Userid82001nameAndroid
]code200
(continues on next page)
4 Chapter 2 Features
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
Try it yourself
Test it online
21 Examples 5
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
6 Chapter 2 Features
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
THREE
SERVER-SIDE DEPLOYMENT
This chapter shows how to make installation with Eclipse for JavaEE or IntelllJ IDEA Ultimate For both firstdownload the project unzip it and save it in a directory you can also clone the project from github
git clone httpsgithubcomTommyLemonAPIJSONgit
31 1 Installing with Eclipse
Prerequisites
bull Java Development Kit(JDK) version 18 or above
bull MAVEN version 30 or above
bull Mysql Oracle
bull Eclipse Java EE IDE for Web Developers with version Mars1 Release (451)
Opening the project with Eclipse
Open Eclipse then select File gt Import gt Maven gt Existing Maven Projects gt Next gt Browse gt Selectthe path of the project gt APIJSON-Java-Server gt APIJSONBoot gt check pomxml apijson-demogt Finish
Preparing the library used in demo
In the menu at the right click libs then right click apijson-ormjar click add as library Apply the same to the restof jar files in libs folder
Add your own database
If you want to add your own database open src-main-java-apijson-demo-server-model-DemoSQLConfigjava Inline 40-61 change return values of getDBUri getDBAccount getDBPassword getSchema to your owndatabase
7
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
This is the file that you need to make changes
Overridepublic String getDBUri()
TODO Change the return value to your ownreturn DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) jdbcpostgresql
rarr˓localhost5432postgres jdbcmysql192168711463306Overridepublic String getDBAccount() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) postgres rootrarr˓
Overridepublic String getDBPassword() TODO Change the return value to your own
return DATABASE_POSTGRESQLequalsIgnoreCase(getDatabase()) null rootOverridepublic String getSchema()
String s = supergetSchema()return StringUtilisEmpty(s true) thea s TODO Change the return
rarr˓value to your own For herechange thea to your databases name
8 Chapter 3 Server-side Deployment
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
Running the application
In Eclipse in the menu on the top click Run gt Run As gt Java Application gtchoose APIJSONApplication gt OK
Then copy and paste link httplocalhost8080get to your browser to see if it returns the succesful message
32 2 Importing database
This project needs MySQL Server and MySQLWorkbench Please make sure that both of them are installed
My configuration
bull Windows 7 + MySQL Community Server 5716 + MySQLWorkbench 637
bull OSX EI Capitan + MySQL Community Server 5716 + MySQLWorkbench 638
bull Systems and softwares are all 64 bit
Select MySQLWorkbench gt Enter a connection gt Click Server menu gt Data Import gt Select the path of yoursql file gt Start Import gt Refresh SCHEMAS Now you should see tables are added successfully
You can also import demo sql tables in MySQL folder to test the app
32 2 Importing database 9
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
33 3 Installing with IntellIJ IDEA Ultimate
331 Opening the project
Open gt Select the path of the projectAPIJSON-Java-ServerAPIJSONBoot gt OK
332 Preparing the library used in demo
In libs right-click apijson-ormjar gt Add as Library gt OK Apply this to all jar files in libs
333 Running the application
In the menu on the top Run gt Run gt Edit Configurations gt + gt Application gt Configuration
In Main class choose APIJSON Application
In Use classpath of module choose apijson-demo
Click Run in the bottom
Note After running you should see test logs and finally it would show lsquoAPIJSONrsquo (APIJSON has launched) If itshows error messagelsquoThe address is already in usersquo that means port 8080 has been used You need to change the portSee how to change ports for a Spring Boot Application
Then copy and paste link httplocalhost8080get to your browser
If itrsquos successful it returns with
code 200msg success
10 Chapter 3 Server-side Deployment
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
FOUR
CLIENT-SIDE DEPLOYMENT
41 1 For Android app
Make sure you have either ADT Bundle or Android Studio installed
My configuration
bull Windows 7 + JDK 170_71 + Android Studio 22
bull OSX EI Capitan + JDK 180_91 + Android Studio 30
bull All the systems and software are 64 bit
1Importing
Select Open an existing Android Studio project gt Select the path of APIJSON-MasterAPIJSON-AndroidAPIJSONApp(or APIJSONTest gt OK
2Running
Run gt Run app
3Testing
In the browser send a request to the server to see if it responses
If the default url is not available change it to an available one such as the IPV4 address which is running APIJSONproject back side Then click the request button again
42 2For iOS app
Open xCode then APIJSON-MasterAPIJSON-iOSAPIJSON-Swift gt Open
In xCode Product gt Run
11
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
43 3 For Javascript
You can use either an IDE or text editor like sublime Atom etc Webstorm is recommended
While using a text editor you just open the html file in the APIJSON-JS folder
You can also open it with Vue javascript framework Click here to learn more
12 Chapter 4 Client-side Deployment
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
FIVE
API DESIGN STYLE GUIDE
This chapter introduces methods in APIJSON These methods are
GET It provides a general way to retrieve resourcesHEAD It provides a general way to count resources satisfying specifics in the request bodyGETS It requests for highly secured and confidential data like bank accounts birth datesHEADS Itrsquos 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 updateedit an existing resourceDELETE 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 commonlyreferred to as the request ldquoverbrdquo 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 pathAll URL paths are relative to the base URL
51 1 APIJSON Methods
511 GET
A general way to retrieve resources
base_urlget
Request
TableName conditions
eg Request a post with id = 235 in table PostPostid 235
Response
13
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
TableNamecode200msgrdquosuccessrdquo
eg The returned responseMomentid235userId38710content
code200msgsuccess
512 HEAD
A general way to count resources satisfying specifics in the request body
base_urlhead
Request
TableName conditions
eg Get the number of posts posted by the user whose id = 38710PostuserId38710
Response
TableNamecode200msgsuccesscountcode200msgsuccess
egPostcode200 msgsuccess count10code200
(continues on next page)
14 Chapter 5 API design style guide
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
(continued from previous page)
msgsuccess
513 GETS
Request for highly secured and confidential data like bank accounts birth dates
base_urlgets
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object The tag is usually therarr˓related tables name
Except that the structure is the same as GET
Response
Same as GET
514 HEADS
Itrsquos used for getting counts of highly secured resources(eg bank accounts)
base_urlheads
Request
You need to nest a key-value pair
ldquotagrdquo tag
at the top level of the request json object
Except that the structure is the same as HEAD
Response
Same as HEAD
51 1 APIJSON Methods 15
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
515 POST
The POST method creates new resources under the specified parent resource(TableName)
base_urlpost
Request
TableNametagtag
Note the id in the object TableName has been generated automatically whenrarr˓table is built and canrsquot be set by the user here
eg A user with id = 38710 posts a new post
Post
userId38710contentAPIJSON lets interfaces and documents go hell
tagMoment
Response
Moment
code200msgsuccessid
code200msgsuccess
If the request is successful it should return following object
TableName
code200msgsuccessid38710
code200msgsuccess
16 Chapter 5 API design style guide
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
516 PUT
The PUT method asks the server to updateedit an existing resource The part that will be modified is included in therequest body
base_urlput
Request
TableName
idid
tagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example makes request to update the content made by id = 235
Post
id235contentAPIJSON lets interfaces and documents go hell
tagPost
Response
Same as POST
517 DELETE
The DELETE method deletes the specified resource
base_urldelete
Request
TableName
ididtagtag
You need to either specify the id in the TableName object like the example aboverarr˓or add a id object in the request body
The following example send a request to delete comments made by id = 100110120
Comment
id[100110120]
(continues on next page)
51 1 APIJSON Methods 17
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
(continued from previous page)
tagComment[]
Response
TableNamecode200msgsuccessid[][]count3
code200msgsuccess
The response to the request in the example above
Commentcode200msgsuccessid[][100110120]count3code200
msgsuccess
Note
1 TableName means the name of the table that a user interacts with Itrsquos a string with the first letter capitalizedIt can be any combination of letters numbers and underscores As a key its value is a jsonObject which mayinclude columnsrsquo names in the table
2 ldquotagrdquotag needs to be included when the request method is neither GET nor HEAD The value tag is thekey of the returned jsonObject in the response body Usually itrsquos the name of the related table
3 The request form under GET and HEAD methods are very flexible The request jsonObject can be nested manylevels However other methods need to be constrained by adding tags etc The structure of the request bodyneeds 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 havesomething different while the response bodies are the same
5 When transmit through HTTP protocal all the API methods (getgetsheadheadspostputdelete) use HTTPPOST verb
6 All jsonObjects are seen as variables or folders with the form of It can store objects or associativearrays
7 Each object is related to an individually-addressable resource which has an unique address
18 Chapter 5 API design style guide
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
52 2 Functional Key-Value Pairs
Get data in an array getkey[]tableName
The part after the colon is a JSONObject The key is optional When key is as the same as the tableName theJSONObject will be in a simplified form For example User[]Userid will be writtenas User[]id
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquo
In this example the request is to GET 3 usersrsquo information The response includes 3 users informationwith all categories saved in an array
Get filtered data getkey[]tableNamekey2[]
Specifically in this part key2[] the part after the colon is a JSONArray which contains key2rsquos values Thispart is to specify the conditions that the return should satisfy
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquo[387108200170793]
This example shows how to get usersrsquos information with id equals 387108200170793
Get data with comparison operation getkey[]tableNameidlt=80000gt90000
Just as the comparison operation functions in SQL itrsquos used here to get resources in a range It dosnrsquot need to benumbers though
Example
getldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquoidrdquordquolt=80000gt90000rdquo
In SQL itrsquod be idlt=80000 OR idgt90000 which means get User array with idlt=80000 | idgt90000
Get data that contains an element getkey[]Userkey2ltgt[object]
This also used when the user wants to get data that meets specific conditions key2 must be a JSONArray whileobject cannot be JSON
Example
ldquogetldquoUser[]rdquoldquocountrdquo3rdquoUserrdquoldquocontactIdListltgtrdquo38710rdquo38710
In this example it requests 3 User arrays whose contactIdList contains 38710 In SQL this would bejson_contains(contactIdList38710)
See if it exists getkeykey2fromtableNametableName
In this request url means EXISTS key2 is the item you want to check
Example
`ldquoUserrdquo
52 2 Functional Key-Value Pairs 19
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
ldquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquoldquomomentIdrdquo15 lthttpapijsoncn8080get7B22User227B22id7D7B227B22from2222Comment2222Comment227B22momentId22157D7D7D7Dgt`_
In this example the request is to check if the id whose momentId = 15 exists The SQL form wouldbe WHERE EXISTS(SELECT FROM Comment WHERE momentId=15)
Include functions in url parameters getTablekeyvalue key()function (key0key1)
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-() gt analyze the current object gt analyze key() gt analyze childobject gt analyze key+()
Example
getldquoMomentrdquoldquoidrdquo301rdquoisPraised()rdquordquoisContain(praiseUserIdListuserId)rdquo
This will use function boolean isContain(JSONObject request String arrayString value) In this case client will get ldquois praisedrdquo true (In this case clientuse function to testify if a user clicked lsquolikersquo button for a post)
Refer a value
keykey0key1refKey
Use forward slash to show the path The part before the colon is the key that wants to refer The path after the colonstarts with the parent level of the key
Example
`rdquoMomentrdquo
ldquouserIdrdquo38710
ldquoUserrdquo ldquoidrdquordquoMomentuserIdrdquo lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
In this example the value of id in User refer to the userId in Moment which means Userid =MomentuserId After the request is sent idMomentuserId will be id38710
Subquery expression
keyrange ALLfromTableTable
Range can be ALL ANY It means which table you want to query Itrsquos very similar to how you query in SQL Youcan also use COUNT JOIN etc
Example
`rdquoidrdquo ldquofromrdquordquoCommentrdquo ldquoCommentrdquo ldquocolumnrdquordquomin(userId)rdquo
20 Chapter 5 API design style guide
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
lthttpapijsoncn8080get7B22User227B22id227B22from2222Comment2222Comment227B22column2222min(userId)227D7D7D7Dgt`_
code WHERE id=(SELECT min(userId) FROM Comment)
Fuzzy matching key$SQL search expressions =gt key$[SQL search expressions]
Any SQL search expression can be applied here
Example
ldquoname$rdquordquomrdquo
In SQL itrsquos name LIKE m meaning that get User with lsquomrsquo in name
Regular Expression key~regular expression =gt key~[regular expression]
It can be any regular expressions Advanced search is applicable
Example
ldquoname~rdquordquo^[0-9]+$rdquo
In SQL itrsquos name REGEXP ^[0-9]+$
Get data in a range keystartend =gt key[startend]
The data type of start and end can only be either Boolean Number or String Eg ldquo2017-01-012019-01-01rdquo[ldquo190000rdquo ldquo82001100000rdquo] Itrsquos used for getting data from a specific time range
Example
ldquodaterdquordquo2017-10-012018-10-01rdquo
In SQL itrsquos date BETWEEN 2017-10-01 AND 2018-10-01 meaning to getUser data that registered between 2017-10-01 and 2018-10-01
Make an alias namealias
This changes name to alias in returning results Itrsquos applicable to column tableName SQL Functions etc but only inGET HEAD requests
Example
getldquoCommentrdquoldquocolumnrdquordquoidtoIdparentIdrdquordquoidrdquo51
In SQL itrsquos toId AS parentId Itrsquoll return parentID instead of toID
Add expand an item key+numberstringarray
The type of value on the right of the colon is decided by key Types can be Number (such as 82001) String (such asldquourl0rdquo) JSONArray (such as [ldquourl0rdquordquourl1rdquo]) The method can only be PUT
Example
52 2 Functional Key-Value Pairs 21
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
code ldquopraiseUserIdList+rdquo[82001]
In this example add id 82001 to the praiserrsquos list In SQL it should bejson_insert(praiseUserIdList82001)
Delete decrease an item ldquoKey-rdquonumberstringarray
It has the contrary function of ldquokey+rdquo
Example
balance-10000
This example subtract 100 in the balance In SQL it would be balance = balance - 10000
Logical Operators amp|
amp| refer to AND OR NOT in SQL respectively The basic form to use them are keyampconditionskey|conditions keyObject
By default conditions of the same key are connected with | operator As for differentkeyconditons`pairs the default operator among them is code`amp
Example
headldquoUserrdquoldquoidamprdquordquogt80000lt=90000rdquo
In SQL itrsquos idgt80000 AND idlt=90000 meaning id needs to be idgt80000 amp idlt=90000
headldquoUserrdquoldquoid|rdquordquogt90000lt=80000rdquo
Itrsquos the same as idgt90000lt=80000 In SQL itrsquos idgt80000 OR idlt=90000 meaningthat id needs to be idgt90000 | idlt=80000
headldquoUserrdquoldquoidrdquo[8200138710]
In SQL itrsquos id NOT IN(8200138710) meaning id needs to be (id=82001 |id=38710)
53 3 Build-in string functions part one
countInteger
This is used to set the maximum number of the returning resources The maximum number the system supports is100 Without this itrsquoll return the maximum number of results that meet the condition
Example
getldquo[]rdquoldquocountrdquo5rdquoUserrdquo
This example requests 5 Usersrsquo data
pageInteger
This is to indicate the page number starting with 0 The max number can be 100 Itrsquos usually used withcountInteger
Example
22 Chapter 5 API design style guide
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
getldquo[]rdquoldquocountrdquo5rdquopagerdquo3rdquoUserrdquo
This example get Users data on page 3 with the total number of 5
queryInteger
When the Integer is 0 it means get the resource When itrsquos 1 it means counting the number and returning thenumberWhen itrsquos 2 it means returning both
Example
getldquo[]rdquoldquoqueryrdquo2 User ldquototalrdquordquo[]totalrdquo
joinampTable0key0ltTable1key1
The joining table functions are represented by symbols
ldquoltrdquo - LEFT JOIN
ldquogtrdquo - RIGHT JOIN
ldquoamprdquo - INNER JOIN
ldquo|rdquo - FULL JOIN
ldquordquo - OUTTER JOIN
Example
getldquo[]rdquoldquojoinrdquo ldquoampUseridltCommentmomentIdrdquo ldquoMomentrdquoldquoUserrdquoldquonamerdquordquotrdquo ldquoidrdquo ldquoMomentuserIdrdquo ldquoCommentrdquoldquomomentIdrdquo ldquoMo-mentidrdquo
This examples is equal to SQL expression Moment INNER JOIN User LEFT JOIN Comment
54 4 Build-in string functions part two
combineampkey0ampkey1|key2key3key4key5ampkey6key7
This function combines conditions that have been listed to request data Itrsquoll group conditions according to their typesIt uses logical operators(amp|) to connect among groups while within a group itrsquoll follow the order that conditionshave been listed So itrsquoll become code`(key0 amp key1 amp key6 amp other keys) amp (key2 | key3 | key7) amp (key4 | key5) `
Thecodeother keys means keys that arenrsquot included in combine function By default itrsquos connected by AND
Example
getldquoUser[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquoidnametagrdquordquoname~rdquordquoardquordquotag~rdquordquoardquordquocombinerdquordquoname~tag~rdquo
This example request User objects whose name or tag includes ldquoardquo
columncolumnfunction(arg)
This function defines which colunms will be returned
Example
54 4 Build-in string functions part two 23
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
getldquoUserrdquoldquocolumnrdquordquoidsexnamerdquordquoidrdquo38710
This request only returns colunms id sex name The returning follows the same order
ordercolumn0+column1-
This function can set descendent or ascendent order of returning data within a column
Example
getldquo[]rdquoldquocountrdquo10rdquoUserrdquoldquocolumnrdquordquonameidrdquordquoorderrdquordquoname-idrdquo
This example requests data following descendent order in name column while the default order in idcolumn
groupcolumn0column1
This function groups data with columns If the tablersquos id has been declared in column then the id needs to beincluded in group
Example
getldquo[]rdquoldquocountrdquo10rdquoMomentrdquoldquocolumnrdquordquouserIdidrdquordquogrouprdquordquouserIdidrdquo
This example returns id grouped by userId
havingfunction0()value0function1()value1function2()value2
This function is as same as the HAVING function in AQL Normally itrsquos used with group
Example
getldquo[]rdquoldquoMomentrdquoldquocolumnrdquordquouserIdmax(id)rdquordquogrouprdquordquouserIdrdquordquohavingrdquordquomax(id)gt=100rdquo
This example get an array of Moment with userID and id where id gt=100 grouped by userId
schemasys
24 Chapter 5 API design style guide
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
SIX
WHAT APIJSON HAS ACHIEVED
61 Functions
bullRegisteration and login
bullCRUD and remote procedure call(RPC) of functions
bullSetting orders and pages on returned data
bullCalculating and grouping data
bullFuzzy matching search
bullRegular expressions
bullJoining tables subquery and other SQL functions
62 Request Methods
The APIJSON supports the following request methods
GETHEADGETSHEADSPOSTPUTDELETE
For details of these requests methods see design rules
63 Request body structures
ldquoTablerdquo
ldquoTable0rdquo ldquoTable1rdquo ldquoTable2rdquo
ldquo[]rdquo ldquoTablerdquo
ldquo[]rdquo ldquoTable0rdquo ldquoTable1rdquo ldquoArray0[]rdquo etc
25
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
APIJSON Docs Release 100
64 Response body
The reponse body structure will be the same as request body structure
65 Build-in functions
key[] retrieve data arrays
key[123] Add constraints on returned data
keylt=10length(key)gt1 Add constraints on returned data
key()function(arg0arg1) RPC of functions
keykey0key1targetKey Refer a value
key$abc Fuzzy machting research
key~^[0-9]+$ Include regular expressions
key2018-01-012018-10-01 Add constraints on returned data
key+[1] AddExpand data
key-88888 ReduceDelete data
namealias Make an alias
combinename~tag~ Set more than two conditions
columnidsexname Set returned value
groupuserId Group data
havingmax(id)gt=100 Add aggregate functions
orderdate-name+ Set orders
schemasys
databasePOSTGRESQL Interact with differentrarr˓databases
explaintrue Performance analysis
roleLOGIN Set the visiting role
26 Chapter 6 What APIJSON has achieved
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-
CHAPTER
SEVEN
INDICES AND TABLES
bull genindex
bull modindex
bull search
27
- About APIJSON
- Features
- Server-side Deployment
- Client-side Deployment
- API design style guide
- What APIJSON has achieved
- Indices and tables
-