Authoring your REST APIs
What to expect from this post?
REST APIs is the trend in the town these days and having worked on REST APIs for a few years, recently going through setting up our new application on REST, this post intends to add some practical ingredients to the REST application development context.
Below are few pointers to author your REST APIs:
Design REST APIs not to one user interface
The REST APIs should be designed generic and must not tie with the user interface. There could be many versions of user interface that different UX designers can come up with. Also, what holds 'true' today might not be the same tomorrow. Infact, you can have customers using your APIs and have completely different user interfaces.
How do we deal with this?
Pretty simple? Not really.. Design REST APIs that can serve different user interfaces. Yes, this is more work. But, if you consider different user interfaces, you will design your system in a manner that is optimal for different user interfaces. Remember, design is something which is not very easy to change once you have your APIs being consumed. Do it right the first time.. at least, try to !
An example of how this can impact your design :
We decided to provide a macro level API which operate on the complete object graph and granular APIs which operate on one level entities. To achieve this, we had to design our hibernate entities differently - we implemented 'CascadeType.DELETE' to delete the complete object graph on One-To-Many relations and used 'session.merge' for inserting/updating these relations.
We decided to provide a macro level API which operate on the complete object graph and granular APIs which operate on one level entities. To achieve this, we had to design our hibernate entities differently - we implemented 'CascadeType.DELETE' to delete the complete object graph on One-To-Many relations and used 'session.merge' for inserting/updating these relations.
On-demand REST APIs
Your REST APIs can be consumed by variety of clients - servers, browsers, thick clients. Do not design your REST APIs for a particular client.
Communication
Browsers can handle JSONs well, some clients handle XML better. Your REST APIs should support different media types .. communicate in language that the client demands !
Selective fetches
You do not need all the data all the time. Some client just need a few attributes or just the meta. Provide a way to select the data you need from the API. For example, mobile interface shows just the product name and price. No need to fetch the product description, image .. provide just what the client demands!
Graceful, precise, meaningful exceptions
Your APIs should precisely tell what went wrong!
Do not respond with complete verbiage of your application stack !
REST APIs in case of an exception should respond with:
1. HTTP status code
2. Error code
3. Error message
Diligent HTTP Methods(GET, POST, PUT, PATCH, DELETE)
There are few guidelines around Resource URIs and methods:
- Use GET to retrieve, POST to create, PUT to update, DELETE to delete
- Use 'plural' resources as resource identifiers
- Do not use method names in URIs like 'CreateXXX', 'GetXXX, 'DeleteXXX'
- Use Path parameters for required parameters and query parameters for optional ones
So far so good.
Any exceptions to the rule(s)?
Yes, there a few tricky ones where you can choose to go otherwise..
- Use a 'POST' for bulk delete of resources. Servers like Tomcat do support a body in 'DELETE', but not all elements in the pipeline might support the same.
- Use a 'PATCH' for partial update of resource. Saves the bandwidth since you won't pass along the full object representation.
- Use a 'POST' for APIs like advanced search, sorting, pagination. These APIs might make the GET payload cross the 64K limit. Also, not all elements of the network might be supporting the GET payload.
No comments:
Post a Comment