RESTful Standard Resolved!
Join the DZone community and get the full member experience.
Join For FreeLately I'm trying to build a web application which will be exposed in a RESTfull manner.
There are some general guideline and hints about how to define it, but no explicit standard or accepted schema structure to use.
After reading some info on the web, I think I manage to crack the pattern :-)
I would like to share the rules and structure I formed and hopefully to
get some feedback about it and improve it, so please don't hesitate to
leave notes and point any pain point that structure has.
The high level pattern is:
http(s)://server.com/app-name/{version}/{domain}/{rest-convention}
Where {version} is the api version this interface work with and {domain}
is an area you wish to define for any technical (e.g. security - allow
certain users to access that domain) or business reason (e.g. gather
functionality under same prefix).
The {rest-convention} denotes the set of REST API which is available under that domain.
It has the following convention:
- singular-resourceX/
- URL example: order/ (order is the singular resource X)
- GET - will return a new order
- POST - will create a new order. values are taken from the post content body.
- URL example: order/ (order is the singular resource X)
- singular-resourceX/{id}
- URL example: order/1 (order is the singular resource X)
- GET - will return an order with the id 1
- DELETE - will delete an order with the id 1
- PUT - will update an order with the id 1. Order values to update are taken from the post content body.
- URL example: order/1 (order is the singular resource X)
- plural-resourceX/
- URL example: orders/
- GET - will return all orders
- URL example: orders/
- plural-resourceX/search
- URL example: orders/search?name=123
- GET - will return all orders that answer search criteria (QBE, no join) -order name equal to 123
- URL example: orders/search?name=123
- plural-resourceX/searchByXXX
- URL example: orders/searchByItems?name=ipad
- GET - will return all orders that answer the customized query - get all orders that associated to items with name ipad
- URL example: orders/searchByItems?name=ipad
- singular-resourceX/{id}/pluralY
- URL example: order/1/items/ (order is the singular resource X, items is the plural resource Y)
- GET - will return all items that associated to order #1
- URL example: order/1/items/ (order is the singular resource X, items is the plural resource Y)
- singular-resourceX/{id}/singular-resourceY/
-
- URL example: order/1/item/
- GET - return a new item (transient) that is associated order #1
- POST - create a new item and associate it to order #1. Item values are taken from the post content body.
- URL example: order/1/item/
- singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/
-
- URL example: order/1/item/2/package/
- GET - return a new package (transient) that is associated to item 2 (i.e. how to pack the item) and is associated to order #1
- POST - create a new package and associate it to item #2 & order #1. package values are taken from the post content body.
- URL example: order/1/item/2/package/
One basically can have further nesting as long as the above convention is maintained and no plural resource is defined after another plural resource.
There are further guidelines/notes to make things clear:
- When using plural resource, the returning instances will be those of the last plural resource used.
- When using singular resource the returning instance will be the last singular resource used.
- On search, the returning instances will be those of the last plural entity used.
Hopefully your insight will help me improve this structure and overcome issues which you might came across.
In next post, after this suggested structure will be improved, I will try to give technical examples how to implement it using Spring MVC 3.1
Published at DZone with permission of Gal Levinsky, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.
Trending
-
Alpha Testing Tutorial: A Comprehensive Guide With Best Practices
-
Comparing Cloud Hosting vs. Self Hosting
-
Tactics and Strategies on Software Development: How To Reach Successful Software [Video]
-
TDD vs. BDD: Choosing The Suitable Framework
Comments