RESTful guidline

json-structure.md

usage

• return collection. *http code: 200

[
  {id:1},
  {id:2}
]

• return single object. http code: 200

 {id:1}

• create, update, delete. return none. http code: 200
• if error, http code: 400, return

{"status":OK|NOT_FOUND|UNKNOWN_ERROR}

dont't use. just reference.structure like the structure: https://developers.google.com/maps/documentation/geocoding/

{
  "status": "OK|NOT_FOUND|UNKNOWN_ERROR",
  "result": "array [] (request collection) or object {} (request object) or true|false (request delete, update, create)"
}

restful-guildline.md

ref: http://www.sitepoint.com/creating-crud-app-minutes-angulars-resource/

URL	HTTP Verb	POST Body	Result
/entries	GET	emptry	Returns all entries
/entries	POST	JSON String	New entry created
/entries/:id	GET	empty	Returns single entry
/entries/:id	PUT	JSON String	Updates an existing entry
/entries/:id	DELETE	empty	Deletes existing entry

Use hyphen (-) instead of underscore (_) if multi-words, /report-options/

ref: http://www.soa-probe.com/2012/10/soa-rest-service-naming-guideline.html

• Use path variables to encode hierarchy: /parent/child
• Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2
• Use query variables to imply inputs into an algorithm, for example: /search?q=jellyfish&start=20

Other guidelines include:

• URIs should ideally not change over time.
• Services offering a uniquely identifiable resource via a key should use basic rest notation (e.g. /accounts/(accountid) )
• Services offering optional search/filtering capabilities should use query parameter ? key1 = value & key2 = value notation (e.g. /instruments?ticker=FT)
• Services expecting mandatory arguments over GET should have them as path variables (e.g. /accounthistory/(fromdate)/(todate)
• All rest service names should use strict low case names (e.g. /client)
• The elements of the URI should map to business entities and the mapping should be consistent. For example a business entity named contentpartner should be consistently referred to as contentpartner(s) in all URIs (rather than a mix of partner, cp etc). - A good starting point would be the name of the domain object.
• Parameters that do not define a resource but qualify it (e.g. locale which feeds into the translations of the data) should not form part of the normal URI space. Consider using headers or optional query parameters for these
• Use nouns, not verbs. The power of REST comes through the fact there is a limited verb set (operations) combined with a large set of nouns (or resources). Consequently the manner in which these nouns are constructed is of great importance.
• Avoid suffixes. When designingURIs it is paramount that they refer to the thing that is being operated upon rather than the operation being performed. Secondly, the client is interested in the resource - not the implementation of the server software that powers the service. It is desirable to avoid suffixes such as .jsp or .aspx.
• Use Accepts Header for content negotiation
• Keep It Intuitive. URIs should be human readable or guessable. The easiest way to do this is to construct a URI hierarchy, grouping related items together. Such patterns of category and subcategory are very easy to understand.

More references:

• http://www.restapitutorial.com/lessons/restfulresourcenaming.html
• http://www.ibm.com/developerworks/library/ws-restful/
• http://microformats.org/wiki/rest/urls#URL_Conventions
• http://blog.2partsmagic.com/restful-uri-design/