One JSON is worth a thousand words<\/h2>\n
Let\u2019s see an example of an API response:<\/p>\n
\n{\n \"data\": [\n {\n \"story\": \"Jonatas Baldin was writing a blog post.\",\n \"created_time\": \"2017-15-01T00:02:57+0000\",\n \"id\": \"624510964324764_1046909755418214\"\n },\n ]\n}\n<\/code><\/pre>\nThis snippet of data, called JSON<\/a>, is an example of how a smartphone sees a Facebook status message, gathered from the Facebook API<\/a>. Pretty neat, right?<\/p>\nNow imagine that you are an engineer at Facebook, responsible for this API. You wake up one day and decide to change the <\/span>id<\/span><\/i> field name to <\/span>message_id<\/span><\/i>. Well, this small change could break Facebook. For real. All devices that depend on the previously-defined structure would now stop being able to collect and display the content to the user. Definitely not a great day at work.<\/span><\/p>\nThe good, the bad and the ugly<\/h2>\n
A bad API design \u2013 or the lack of it \u2013 will, sooner or later, cause all kinds of trouble:<\/span><\/p>\n\n- Absence of consistency<\/strong>: once an API grows, the endpoints tend to be created just to fulfill immediate needs.<\/span><\/li>\n
- Difficulty to scale<\/strong>: there\u2019s no reference when troubleshooting an endpoint.<\/span><\/li>\n
- Hard to learn<\/strong>: a steep learning curve to consume data from and develop the API.<\/span><\/li>\n
- Performance issues<\/strong>: throwing unplanned API code usually creates performance bottlenecks on the long run. <\/span><\/li>\n
- APIs tend to be forever<\/strong>: it\u2019s always better to get it right at the first chance.<\/span><\/li>\n<\/ul>\n
![\"sad\"](\"https:\/\/ckl-website-static.s3.amazonaws.com\/wp-content\/uploads\/2017\/02\/ezgif.com-resize.gif\")
<\/p>\n
An API is a contract between your application and its users. It can\u2019t be changed abruptly without causing chaos for those who already signed it and it shouldn’t be built without forethought. This is where design<\/a> enters: the creation of a plan or convention for the construction of an object, system or measurable human interaction.<\/p>\nFirst things first: Let’s talk HTTP<\/h2>\n
Before diving into API code, let\u2019s get a glimpse of the Hypertext Transfer Protocol<\/strong>. HTTP, as the name suggests, is used to transfer data on the web. It has a set of rules on how clients and servers should exchange information. Its main components are:<\/p>\n\n- URL:<\/b> where your resources are on the web, the address of your endpoint. An example is using <\/span>http:\/\/example.org\/users<\/span><\/a> to list your users.<\/span><\/li>\n
- Request methods:<\/b> the action a client wants to perform on a specific endpoint. <\/span>GET<\/b> is used to retrieve a resource, <\/span>POST, to <\/b>create one, <\/span>PUT<\/b> and <\/span>PATCH<\/b> to update an existing one, and <\/span>DELETE<\/b>\u2026 well, deletes stuff.<\/span><\/li>\n
- Headers:<\/b> contain information about the client or the server. For instance: content type (format), method, authentication token and others.<\/span><\/li>\n
- Body:<\/b> the data sent to the server or received by the client. JSON is the <\/span>de facto<\/span><\/i> standard. <\/span><\/li>\n
- Status code:<\/b> a three-digit number which tells the request status. To summarize,
2xx<\/code> statuses means success, 4xx<\/code> means client errors and 5xx<\/code> means service errors. You can get a full list <\/span>here<\/span><\/a> or <\/span>here<\/span><\/a>.<\/span><\/li>\n<\/ul>\nLet’s see an HTTP request\/response example:<\/span><\/p>\n\n\nClient request:<\/b>\nGET \/users\/1 HTTP\/1.1\nHost: www.example.org\/users\n\nServer response:<\/b>\nHTTP\/1.1 200 OK\nContent-Type: application\/json\nDate: Sun, 19 Feb 2017 00:43:51 GMT\n\n{\n \"id\": 1,\n \"first_name\": \"Jonatas\",\n \"fast_name\": \"Baldin\",\n \"role\": \"Caker\"\n}\n<\/code><\/pre>\nGood API design demands good specifications<\/h2>\n
There are some specifications to help you out when designing your API. The most used ones are Swagger<\/strong> with pure JSON, RAML<\/strong> with YAML notation and API Blueprint<\/strong> backed by the markdown syntax. I felt in love with the latter: even though it is the new cool kid in the neighborhood, it\u2019s already mature enough and delightful to work with. That\u2019s the one I\u2019ll be covering here.<\/span><\/p>\nFrom the official website:<\/span><\/p>\nAPI Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs.<\/span><\/p><\/blockquote>\nIt\u2019s an open source, focused on collaboration, easy to learn and well-documented specification created by Apiary with design-first<\/a> in its core, surrounded by awesome tools: from mock server generators to full-feature life-cycle solutions.<\/span><\/p>\nIn addition to Blueprint, there\u2019s MSON<\/strong> (Markdown Syntax Object Notation), which defines data structures in a human-readable way. Instead of writing manually the endpoints body data, you represent them in reusable objects. Pretty nifty, huh?<\/span><\/p>\nHere\u2019s what you need to know to get started:<\/span><\/p>\n\n- API Name, Description and Metadata<\/strong>: describe a little bit about the API and the Blueprint version.<\/span><\/li>\n
- Resource Groups<\/strong>: group of related resources, like Users.<\/span><\/li>\n
- Resource<\/strong>: Defines a unique resource, its endpoint and action.<\/span><\/li>\n
- Parameters<\/strong>: Used in an endpoint to specify a dynamic parameter, like an ID or query search.<\/span><\/li>\n
- Response<\/strong>: The content-type, HTTP status code and body data.<\/span><\/li>\n<\/ul>\n
Besides that, there\u2019s Apiary<\/a>. It\u2019s a collaborative platform to create, render, test and serve your API. They have a free plan for public projects and you can sign up directly from your GitHub account to create your own designs.<\/span><\/p>\nHere\u2019s a Blueprint code sample:<\/span><\/p>\nFORMAT: 1A\nHOST: http:\/\/cakes.ckl.io\/\n\n# Cakes API\nCakes is an API used to store and consume information about the most loved Cakes here at Cheesecake Labs.\n\n# Group Cakes\n\n## Cakes [\/cakes\/]\n\n### List all Cakes [GET]\n\n+ Response 200 (application\/json)\n\n+ Attributes (array[Cake])\n\n# Data Structures\n\n## Cake (object)\n+ id: `1` (string, required) - The unique ID of a Cake.\n+ name: `Cheesecake` (string, required) - The name of a Cake.\n+ rating: `5\/5` (string, optional) - The rating of a Cake.\n<\/code><\/pre>\nIf you access the project<\/a> above, you\u2019ll see a prettily-rendered page. Now the awesome part: a mock server is automatically created for every project \u2013 look at this<\/a>! See the magic? No code was needed to make it work. Anyone with basic knowledge of HTTP and Blueprint can create a mock API and get feedback from customers.<\/p>\nThe example above is as simple as it can get. You can check the Blueprint tutorials and documentation<\/a> to go deeper into its syntax and read the specs here<\/a>. Also, this is an open-source project \u2013 any contribution from the community is welcomed.<\/p>\nCongratulations! Now you are armed with the knowledge necessary to design your APIs. But before you start rocking your systems, here are some little tips to keep on your toolbelt:<\/p>\n
Dos and Don’ts<\/h2>\n
We have walked a long path together, from understanding what is an API and why its design matters, passing by the HTTP protocol and landing on Blueprint API, giving you the foundation to start creating your own designs. I\u2019ll list some amazing dos and don’ts. Note that these aren\u2019t rules, just best practices you generally find on the web.<\/span><\/p>\n <\/p>\n
Treat endpoint actions as CRUD(L) operations<\/b><\/p>\n
Our \/cakes\/<\/code> endpoint may have Create, Read, Update, Delete and List operations. You can construct these actions with HTTP verbs and the URL, like:<\/span><\/p>\n\n- List<\/strong>:
GET \/cakes\/<\/code><\/span><\/li>\n- Create<\/strong>:
POST \/cakes\/<\/code><\/span><\/li>\n- Read<\/strong>:
GET \/cakes\/1\/<\/code><\/span><\/li>\n- Update<\/strong>:
PATCH \/cakes\/1\/<\/code><\/span><\/li>\n- Delete<\/strong>:
DELETE \/cakes\/1\/<\/code><\/span><\/li>\n<\/ul>\n <\/p>\n
Correctly use the HTTP methods<\/b><\/p>\n
GET<\/code> is for getting, POST<\/code> if for posting. Don\u2019t use POST<\/code> if you just want a list of Cakes.<\/span><\/p>\n <\/p>\n
HTTP has methods, use them!<\/b><\/p>\n
POST \/cakes\/createCake<\/code><\/p>\nYou don\u2019t need to specify the action in the URL, we already know that POST<\/code> creates something.<\/span><\/p>\nPOST \/cakes\/<\/code><\/span><\/p>\nCleaner URL, also telling us that probably the other methods will work as expected, like GET \/cakes<\/code>.<\/span><\/p>\n <\/p>\n
Singular or Plural? Plural!<\/b><\/p>\n
GET \/cakes<\/code> should return a list of Cakes, so GET \/cake\/1<\/code> should return the first Cake, right? Unfortunately, no. Even though it makes sense in our language, it will just confuse clients and developers with one more endpoint.<\/span><\/p>\n <\/p>\n
Searching, ordering, limiting? Use query parameters!<\/b><\/p>\n
This feature allows you to specify some filtering on List endpoints, here\u2019s an example:<\/span><\/p>\nGET \/cakes\/?name=apple<\/code><\/span><\/p>\nIf implemented, should list all the Cakes with apple in the name.<\/span><\/p>\nGET \/cakes\/?name=apple&rating=4<\/code><\/span><\/p>\nYou can also concatenate parameters with &, search for apple and a 4 rating.<\/span><\/p>\n <\/p>\n
Return. Errors. With. 4xx.<\/b><\/p>\n
If you want to take just one thing from this article, make sure it\u2019s this one: everybody freaking hates a response with HTTP 2xx<\/code> and a message of error! Use the correct codes:<\/span><\/p>\n401<\/strong>: Unauthorized access, where the authorization process wasn\u2019t done correctly.<\/span><\/p>\n403<\/strong>: Forbidden access, the client is authorized, but has no access to the resource.<\/span><\/p>\n404<\/strong>: The famous not found, indicating the resource is not available.<\/span><\/p>\n <\/p>\n
Describe your errors with clarity<\/b><\/p>\n
When something fails, inform the client about what happened and how it can recover. Here\u2019s a nice way to do it:<\/span><\/p>\n\n{\n \"error\": {\n \"type\": \"Authentication Error\",\n \"details\": \"Authentication could not be established with the given username and password\",\n }\n}\n<\/code><\/pre>\nEveryone understands that.<\/span><\/p>\n <\/p>\n
I\u2019m a teapot<\/b><\/p>\n
![\"thumbs](\"https:\/\/ckl-website-static.s3.amazonaws.com\/wp-content\/uploads\/2017\/02\/giphy-3.gif\")
<\/p>\n