Designing A RESTful API Tips

Understanding The HTTP Method Types

$api->get('products', 'ProductController@getProduct'); 
$api->post('products', 'ProductController@addProduct');
$api->put('products', 'ProductController@updateProduct');
$api->delete('products', 'ProductController@deleteProduct');

Use Correct Return Types

Successful Codes

Data Errors

Auth Errors

Versioning

GET example.com/api/v1/posts GET example.com/api/v2/posts

How To Name Your Endpoints

Use of Singular or Plural Urls

Filtering With Querystrings

GET example.com/api/v1/posts?per_page=10&category=5

Using Response Envelopes

{
{ "foo" : "boo" },
{ "foo2" : "boo2" },
{ "foo3" : "boo3" },
{ "foo4" : "boo4" },
{ "foo5" : "boo5" }
}
{
data: [
{ "foo" : "boo" },
{ "foo2" : "boo2" },
{ "foo3" : "boo3" },
{ "foo4" : "boo4" },
{ "foo5" : "boo5" }
]
}
{
data: [
{ "foo" : "boo" },
{ "foo2" : "boo2" },
{ "foo3" : "boo3" },
{ "foo4" : "boo4" },
{ "foo5" : "boo5" }
],
links: { "next": "", "prev": "" }
}

Allow Pagination

{
"total": 50,
"per_page": 15,
"current_page": 1,
"last_page": 4,
"next_page_url": "http://laravel.app?page=2",
"prev_page_url": null,
"from": 1,
"to": 15,
"data":[
{
// Result Object
},
{
// Result Object
}
]
}

Security — Access Tokens

JWT — Access Token

Refreshed Tokens

Throttling

How To Display Errors

{
"code" : 1234,
"message" : "Something bad happened :(",
"description" : "More details about the error here"
}
{
"error" : {
"code" : 404,
"message" : "Page not found"
}
}

Object Responses From Updates & Creation

Including Related Resources

{
"data": {
"id": 100,
"title": "The blog post",
"featured_image": 1,
"author_id": 1,
"category_id": 1
}
}
{
"data": {
"id": 100,
"title": "The blog post",
"featured_image": 1,
"author_id": 1,
"author": {
"id": 1,
"name": ""
},
"category_id": 1,
"category": {
"id": 1,
"name": ""
},
}
}

snake_case vs camelCase

Documentation

What Practices Do You Use In Your APIs?

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store