Fork me on GitHub

restcookbook.com

How to do stuff RESTful

This question still needs answering. If you like to help, make a pull request for this question.

What is the correct way to version my API?

The "URL" way

A commonly used way to version your API is to add a version number in the URL. For instance:

/api/v1/article/1234

To "move" to another API, one could increase the version number:

/api/v2/article/1234

The hypermedia way

GET /api/article/1234 HTTP/1.1
Accept: application/vnd.api.article+xml; version=1.0

See also

Caveats

Please enable JavaScript to view the comments powered by Disqus.

Topics

Basics (5 recipes)
- How do I let users log into my RESTful API?
- Caching your REST API
- How do I version my REST API?
- What is HATEOAS and why is it important?
- What is the code-on-demand constraint?
HTTP Headers (1 recipe)
- Unsatisfied Accept-Language header
HTTP Methods (5 recipes)
- How do I know which HTTP methods are supported
- When to use PUT or POST
- When to use the PATCH method
- What are idempotent and/or safe methods?
- When to send 4xx or 5xx codes
Mediatypes (1 recipe)
- Is my API RESTful when I use JSON?
Miscellaneous (3 recipes)
- What is the Richardson Maturity Model?
- Are REST and HTTP the same thing?
- Where to find REST presentations
Resources (4 recipes)
- Custom content-types
- Paginating collections
- Using link-types in relations
- Asynchronous operations