API Expertise for Developers: 3 things you should know

If you are a developer looking to succeed in todays software development arena your API know-how is a critical factor. Many software today either consume or produce APIs. Hence you need to be familiar with few factors related to API design and development

1. Know the HTTP Protocol

When you deal with APIs, vast majority of them are using REST style with JSON data formats. HTTP protocol is an inherent part of all the API semantics. You need to have a good understanding on HTTP headers, verbs and status codes.

Headers

HTTP headers let API consumers and API providers pass additional information with requests and responses. An HTTP header consists of its case-insensitive name & value pairs separated by a colon (:).

The Mozilla Developer Network (MDN) provides an easy to follow and understand documentation on HTTP headers. If you are an API developer, you should keep this guide bookmarked or saved for regular access and reference.

Verbs

HTTP Verbs, also known as HTTP request methods, indicate the desired action to be performed for a given resource. For example, given a web resource depicted by URL, would you want to read, write, update or create that resource?

MDN provides a good documentation on HTTP verbs.

The most common HTTP request methods in use are GET and POST. In case of APIs, PUT and DELETE are also useful. But the HTTP request methods usage is not limited to only those four. GET, PUT, POST and DELETE provides you means to handle CRUD (Create, Read, Update, Delete) operations on resources. When you deal with data associated with API resources, CRUD is required, similar to such operations you perform using SQL on a database.

Status Codes

HTTP status codes indicate whether a HTTP request has been successfully completed.

Understanding status codes are very useful when debugging API implementations and application usage. For example, HTTP status codes help determine if an API call failed due to errors on client side or the server side.

MDN provides a good documentation on HTTP status codes.

2. Understand Resources

Resources are the entities that help us represent data in the API implementations. Each resource has a unique address, as depicted by a URL. In other words, each resource is uniquely addressable.

You need to understand the structure of a URL when you use URLs in addressing APIs

Following is an example.

http://example.com:8080/employee/10

There are 4 main elements in this URL

  1. http – protocol used when accessing the URL
  2. example.com – name of the server where the API is hosted on
  3. 8080 – the post over which the server listens for oncoming requests
  4. employee/10 – the resource name, in other words, the employee with ID 10

You can perform CRUD operations using the HTTP verbs.

PUT – Request to create a resource with the given URL

GET – Read the resource at the given URL

POST – Update the resource at the given URL

DELETE – Delete the resource at the given URL

e.g.

GET http://eample.com:8080/employee/10

To understand how to design REST APIs with URLs and HTTP verbs, follow the tutorial on REST workflow design.

3. JSON for Data Representation

When you send requests and receive responses with APIs to resource URLs, you send and receive data over HTTP protocol. The data could be represented using multiple data representation formats such as XML or JSON.  

In today’s API based applications, the most proffered data format to represent resources is JSON.

JSON stands for JavaScript Object Notation, it is a lightweight format for storing and transporting data.

If you are an API developer, you need to be able to understand, construct, debug and design JSON data structures well. Sometimes, you need JSON validator tools to be able to debugs and validate the messages you compose or receive.

Here is a good reference on JSON to keep in handy for your regular reference when you do your API development activities.