Tag Archives: API

Best Practices for API Error Handling

Best-Practices-for-API-Error-Handling

As a web developer, we all don’t want to see Error codes in an API response, neither do you. When it happens to you, it can mean one of two things — there was something wrong in your request or your handling that the API simply couldn’t parse the passed data, or the API itself has so many problems. In either situation, traffic comes to a sudden end, and we start trying to discover the cause and solution for that.

Although being unpleasant, errors, whether in code form or simple error response, are incredibly useful. Error codes are probably the most useful diagnostic element in the API space.

Today, we’re going to discuss about the importance and the usefulness of error responses and handling approaches. There are some common error code classifications the average user will encounter, as well as some examples of these codes in action that you need to know.

The Value of Error Codes
As explained above, error codes are surprisingly, but incredibly useful. Error codes in the response stage of an API are essential in communicating failure from a developer to a user. This stage is a direct communication between client and API. It’s considered as the most important step towards informing the user of a failure, as well as boosting the error resolution process.

An error comes randomly and sometimes it’s beyond our knowledge. That’s why error responses are the only constant, consistent communication that we, as the user, can rely on when an error has occurred. Error codes can both clarify the situation, as well as communicate the intended functionality.

For example, an error code such as “401 Unauthorized – Please Pass Token.” You understand the point of failure in that response, especially that the user is unauthorized. However, you also figure out the intended functionality, which means that the API requires a token, and that token must be passed as part of the request in order to obtain authorization.

With a simple error code and resolution explanation, you have already identified the cause of the error, as well as the intended functionality and method to fix that error. It is very useful, especially for the amount of data that is actually returned.

HTTP Status Codes
Before we deeply discuss about error codes and what makes a code good, we need to sort out the HTTP Status Codes format. These codes are the most frequent status codes that the average user will encounter, not only in terms of APIs but also in terms of general internet usage. Although there are other protocols and have their own system of codes, the HTTP Status Codes dominate API communication, and vendor-specific codes tend to be derived from these ranges.

  • 1XX – Informational

The 1XX range has two basic functionalities. First, in the transfer of information concerning the protocol state of the connected devices — for example, 101 Switching Protocols is a status code noting that the client has requested a protocol change from the server, and that the request has been approved. The 1XX range also elucidates the state of the initial request. For example, 100 Continue, notes that a server has received request headers from a client, and that the server is waiting for the request body.

  • 2XX – Success

The 2XX range notes a range of successes in communication, and combines several responses into specific codes. The first three status codes excellently determine this range, like 200 OK means that a GET or POST request was successful, 201 Created indicates that a request has been brought to completion and a new resource has been created for the client, and 202 Accepted shows that the request has been accepted, and that processing has begun.

  • 3XX – Redirection

The 3XX range is all about the status of the resource or endpoint. When this kind of status code is sent, it confirms that the server is still accepting communication, but that the contacted point is not the accurate point of entry into the system. 301 Moved Permanently denotes that the client request did reach the correct system, but this request and all future requests should be managed by a different URI. This is very convenient both in subdomains and in moving a resource from one server to another.

  • 4XX – Client Error

The 4XX series of error codes is probably the most well-known because of the famous 404 Not Found status, which is a prominent marker for URLs and URIs that are formed in the wrong way. However, other more useful status codes for APIs are in this range.

414 URI Too Long is a common status code, indicating that the data pushed through in a GET request is too long, and should be changed into a POST request. Another common code is 429 Too many Requests, which is used for rate limiting to note a client is attempting too many requests simultaneously that their traffic is being rejected.

  • 5XX – Server Error

The 5XX range is reserved for error codes notably related to the server functionality. Whereas the 4XX range is the client’s responsibility (meaning that it is a client failure), the 5XX range explicitly notes failures with the server. Error codes such as 502 Bad Gateway, which marks the upstream server, has failed and that the current server is a gateway, further reveal server functionality as a method of showing where failure is transpiring.

Making a Good Error Code
With a strongly-built comprehension of HTTP Status Codes, we can start analyzing what actually makes for a good error code, and what makes for a bad error code. Quality error codes not only convey what went wrong, but also why it went wrong.

Excessively obscure error codes are very inconvenient. Imagine that you are trying to make a GET request to an API that manages digital music inventory. You’ve submitted your request to an API that usually accepts your traffic, you’ve passed the correct authorization and authentication credentials, and you think the server is ready to respond.

You send your data, and receive this kind of error code: 400 Bad Request. Without additional data and without more information, what does this mean? It’s in the 4XX range, so you know the problem was on the client side, but it doesn’t explain and solve anything, other than “bad request.”

This explains that a “helpful” error code is not as helpful as it should be. We could easily make that same response helpful and clear with less effort. Good error codes must pass three essential criteria in order to be functional, such as:

  • An HTTP Status Code, so that the source and realm of the problem can be confirmed with ease;
  • An Internal Reference IDfor documentation-specific notation of errors. In some cases, this can substitute the HTTP Status Code, as long as the internal reference sheet inserts the HTTP Status Code scheme or similar reference material.
  • Human readable messagesthat conclude the context, cause, and solution for the existing error.

From this discussion, we can conclude that error codes are useful if inserted with messages conveying what goes wrong and why it goes wrong, topped off with the human readable messages emphasizing the solution that we can take and do to handle it. That way, we can effortlessly handle it when future errors occur spontaneously.

The Easiest Ways to Generate API Documentation

the-easiest-ways-to-generate-api-documentation

As a developer whether you are a web developer or app developer, you may be familiar enough with API documentation. API documentation is an important part of the product offering affordances to the developer community to help them understand exactly what an API offers and how to use it. Below are several hints that you can use to create API documentation easily:

What API Documentation Should Contain

You can create your own API Documentation as you like, since there are no standards on what API documentation should encompass. The important thing is makes it easy for them to understand an API is a good starting point. However, you can follow the list below from established providers in the API economy:

  • A list of the resources with an explanation of the purpose of each in the context of the product or service being offered via the API;
  • Examples of API calls in a variety of languages and tools (cURL, Postman Collections, etc.);
  • Do something meaningful in the context of the product or service the API offers, guides that detail the workflows implicit in using the API i.e. the sequence of API calls. For example, Dwolla offers several guides on how to send or receive money, with branches into different contexts throughout that explain the different aspects of their product offering;
  • An overview of the design principles adopted by the API provider and what that means for aspects adherence to REST (especially hypermedia), HTTP codes, etc.;
  • Information on authentication, including schemes that may be implemented such as OAuth or OpenID Connect;
  • General information on error handling with information on the HTTP return codes that will be returned;
  • User-specific contexts that help developers get to grips with the subject matter more easily. For example, Stripe automatically tailors their API documentation with your API key and secret (when you are logged in) so any code samples are immediately ready to use;
  • An interactive API explorer that allows the developer to readily bring all this information to life.

Interactive Explorers

It is a common thing to have an Interactive Explorers in API specification formats generated from the specification document itself, creating a means for consumers to both learn about and test API calls at the same time. With the help of interactive explorer in understanding a provider’s API, publishing API will be easier. The options are therefore largely dictated by the choice of API specification format, for example:

  • The OpenAPI Specification (aka Swagger) offers Swagger UI, which allows you to generate an interactive explorer with virtually no coding (depending on the completeness of your Swagger specification);
  • Apiary offers an explorer that is generated from API Blueprint and Swagger specifications. It mixes the features of an interactive explorer with a documentation suite as it renders the Markdown documentation in API Blueprint side-by-side with an interactive tool for making sample API calls;
  • Finally, an open-source explorer is offered for the RAML specification format that implements many of the same features as Swagger UI and Apiary.

By using these tools, we hope you can create an easy-to –use reference point for their developer community. However, static documentation may be required to accompany an interactive explorer, if the subject matter of the API is complex or requires high-level explanation not necessarily associated with a resource.

How to Build API in 10 Minutes with Amazon

How to build an API in 10 minutes

As web developer or people who often deal with programming, building an API will surely take your time. Moreover, if you would like to connect your software to application programming interface, maybe you need a brilliantly designed, coder-friendly interface. Besides, if you need something to do with maintaining all the servers a sturdy API capable of handling millions of requests, we understand as sometimes servers are annoying, even for cloud services.

You choose them, provision them, configure them, deploy them, monitor them, meter them. You also the one who determine when to add or remove them but still you need to pay what you used and you didn’t. The explosion of software as a service in recent years has paved the way for the concept of “servers” to be someone else’s problem. But there are several requirements that should be fulfilled when someone wants to build an API in a server. Many of programmers find that you are going to fight with servers before to do an API.

If you dislike the situation and want to find a better way, you can try another technique which is quite simple and fast.

Amazon

For those who hate the idea of handling their own hardware can have a new tool to help them, for about one year ago, Amazon web Services has been released. The good news about this app is that it is not only cheap to stand up an API with API Gateway but it is also quick work, since it only takes ten minutes if you’re copy-pasting, and half an hour if you’re a good typist.

The work can be done into three steps:

  1. Write a request handler
  2. Install it as a Lambda
  3. Create an API in API Gateway, and connect the Lambda to a resource and method.

You can apply the above techniques and hopefully, it will save your time more than before.