Back to New at Nirolution API Tutorial Blog
“API design best practices” – Content:
Best practices for URIs
An important element in the development of an API is the Uniform Resource Identifier. It is an identifier and consists of a string of characters used to identify an abstract or physical resource. Especially on the Internet and for APIs it is almost unthinkable to do without it. But how should the URI for our API be designed?
(But not to be confused with a URL, short for Uniform Resource Locator. A URI, for example, can be a name for an online resource, whereas a URL only reveals the location. Without going into more detail, the main difference is quickly explained by an example. Your name could be a URI because it identifies you exactly, whereas knowing your name (URL) won’t help anyone find your current location.)
First of all, the URI should be short and easy to read. This sounds simple, but takes more time than you think.
Keep in mind!
It’s also important to use consistent names, cases, and patterns.
In the URI, plural nouns should always be used and strictly lowercase or CamelCase should be used. This means that we only work with lowercase names.
So, links between words should be hyphens.
In addition, the URI should only use slashes where they make sense. The URI should never end with a slash.
Bad: Books/21/Chapter/2/
Good: Books/21/Chapter/2
The URI design should be hierarchical as it is the most effective form. For a 1 to n relationship, the URI can be built as follows:
:collection/:item/:sub-collection/:sub-item
An example in practice would be as follows:
/group/group1/persons/person1
If you have a relationship, you can use the same procedure. However, we have two problems with this. What about caching?
If I change something in my backend, nothing happens in the caching layer.
Also, it is unclear which URI query should be updated first.
So what can we do to solve the problem?
We add additional objects. In our example, an object called Membership is added to the groups and people.
Membership in our example contains the groupID and the personID. This way we can easily access the information or delete the person.
Best Pratices for Versioning
An API can change over time. This can change the data or the language. When versioning data, it is important that the meaning is always the same. This is important to not confuse the API consumer.
With language versioning, the language of the API changes or expands. The state remains the same, but it is presented in a different way. It is important that language change is forward and backward compatible.
In order to ensure backward compatibility, it is crucial to use a version identifier on the customer side. On the server side, the new server should be able to handle both languages.
For forward compatibility, it is important how the version identifier is conceptualized. The reason for this is that the client can interpret the version identifier differently. Different algorithms are possible for this. For example, a version identifier can mean that it is the latest version supported by the server or it contains the minimum requirements to execute all requested features.
Best Practices for Error Handling
Error Handing is an important factor for a good API. From the customer’s point of view, the API is a kind of black box. So if something goes wrong and there is no helpful error message, then our client doesn’t know what to do. In the end, this state causes a lot of time and frustration. In the worst case he will switch to another API provider, which can lead not only to a decrease in sales but also to image damage.
The most common error messages are Error tunneling through 200 << ok >> or it is used for each problem of the 500 << internal server error >>. Both solutions are not helpful and should not be used because they are much too general. So the client should be told what the problem was, so that he has the possibility to solve the problem. These are the most common error messages:
The best way to deal with error messages is to clearly tell the developer what happened. It might look like this:
{
"errors" : {
"message": "Sorry, that page does not exsists",
"code" : 34
"more_infor": "http://www.help.com/errors"
}
}
This allows the user to immediately know what went wrong and react accordingly. There should also be a link to explain each error message.
Best practices: Coding
Furthermore you should consider the following programming recommendations:
- It should be as little as possible changeable.
- subclass only where it makes sense to do so.
- Use inheritances or forbid it.
- Don’t let the client do everything a module could do.
- Caution with overloads.
- Use appropriate parameter and return types.
- For input, an interface is better than a class.
- Used input parameter types that are as specific as possible.
- Do not use a string if a better type is available.
- Do not use a floating point for monetary values.
- Use Double instead of Float, as these are much more accurate, i.e. more decimal places.
- Use consistent parameter arrangement across all methods.
- Avoid long parameter lists.
- Use exceptions to point out exceptional conditions.
- Do not violate the principle of the least astonishment.
- Fix errors as they occur.
- Provide any programmatic access to all data in string form.
“Blockchain API design best practices” – Summary:
To develop a good API, it is important to make use of the best practices recommendations. It is important that the URI is short and easy to read. You should also be constant with names etc. and always use plural nouns. Always use lowercase/camelcase, hypen and build the URI hierarchically.
In data versioning it is important that the data is changed but the meaning should always be the same.
In language versioning it is important that the state should be the same, but the data should be represented differently. Here it is decided that it must be both forward and backward compatible.
For error messages, it is imperative to tell the developer what went wrong. A meaningful error message and a link to interpret the problem are crucial for success.
If you follow these API design best practices and follow our programming advice, your API will be a success.
If you want to be informed about the latest updates, follow us on Facebook, Pinterest and Steemit.
