API Best Practices Blog
API Trends: What to expect in 2012 »
Thanks to all who participated in last week's webinar: "API Trends: What to expect in 2012" with Sam @sramji, Anant @jhingran, and Brian @brianpagno.
Here are the video and slides. Thanks for a great interactive session.
We'd love to hear more of your thoughts and questions; please join the conversation on the api-craft forum.
RESTful API Design: making requests »
We've covered singular vs. plural nouns to label your resources, tips for search, handling errors, and more.
Now lets take a look at what some API requests and responses look like for our dogs API.
Create a brown dog named Al
POST /dogsResponse
name=Al&furColor=brown200 OK
{
"dog":{
"id:"1234",
"name": "Al",
"furColor": "brown"
}
}
Rename Al to Rover - Update
PUT /dogs/1234Response
name=Rover
200 OK
{
"dog":{
"id:"1234",
"name": "Rover",
"furColor": "brown"
}
}
Tell me about a particular dog
GET /dogs/1234
Response
200 OK
{
"dog":{
"id:"1234",
"name": "Rover",
"furColor": "brown"
}
}
Tell me about all the dogs
GET /dogsResponse
200 OK
{
"dogs":
[{"dog:{
"id:"1233",
"name": "Fido",
"furColor": "white"}},
{"dog:{
"id:"1234",
"name": "Rover",
"furColor": "brown"}}]
}
Delete Rover :-(
DELETE /dogs/1234Response
200 OK
Next time: chatty APIs.
RESTful API Design: how many versions? »
I've talked about versioning as one of the most important considerations when designing your pragmatic RESTful API.
So it deserves another mention.
Basic versioning recommendations
- Never release an API without a version.
- Make the version mandatory.
- Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has the highest scope (e.g. /v1/dogs).
- Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a granularity of versioning that doesn't work well with APIs--it's an interface not an implementation. Stick with v1, v2, and so on.
How many versions should you maintain?
Maintain at least one version back.
For how long should you maintain a version?
Give developers at least one cycle to react before obsoleting a version.
Sometimes that's 6 months; sometimes it's 2 years. It will depend on your developers' platforms. For example, mobile apps take longer to rev than web apps.
Next time we'll look at making requests to our RESTfully designed APIs.
