In the previous posts, you learned how to design your RESTful API. In this post, you will learn about the best practices of versioning, analytics, how to set up your API root, what your consumers are expecting for results, why and how filtering should work, and caching.
In the post Designing Your RESTful API Part 1: The Nouns, you learned the importance of resources, request headers, and the request body when you defined your RESTful API. In this post, you will learn about the five or so request verbs and what is send back to the client in the response body and the response status code.
Everything is a resource in REST. As you learned in Choosing Between RESTful Web Service, SOAP, Representational State Transfer (REST) is an architecture style or design pattern for creating web services which allow anything connected to a network to something else on the network using Hypertext Transfer Protocol (HTTP).
In this post, you will learn the how to define your resource identifier. In the following post, you will learn how to use the HTTP verbs and response codes. And along the way you will learn many of the principles of a good RESTful API.
Let me second what As Thomas Hunter II writes:
The easier your API is to consume, the more people that will consume it.
Representational State Transfer (REST) is an architecture style or design pattern for creating web services which allow anything connected to a network to something else on the network using Hypertext Transfer Protocol (HTTP).
Typically we think of a RESTful Web Service as one that will get and set data. It works a lot the same way as a web page, but your user doesn’t see the data until it’s time to be displayed.
REST principles are based on the same underlying principles that govern the Web. Those principles are:
- User agents interact with resources, and resources are anything that can be named and represented. Each resource can be addressed via a unique Uniform Resource Identifier (URI).
- Interaction with resources (located through their unique URIs) is accomplished using a uniform interface of the HTTP standard verbs (GET, POST, PUT, and DELETE). Also important in the interaction is the declaration of the resource’s media type, which is designated using the HTTP Content-Type header. (XHTML, XML, JPG, PNG, and JSON are some well-known media types.)
- Resources are self-descriptive. All the information necessary to process a request on a resource is contained inside the request itself (which allows services to be stateless).
- Resources contain links to other resources (hyper-media).