What is Pragmatic RESTful API Design?
As an API developer once you have a perfectly stable data model you need to create an API which is public or which can be used for web applications. It is by far the next logical step in its development. However, once your API goes public so to speak, making changes to its core can be difficult. The only way you are getting around this is to use solid API design guidance in the first place. You will find dozens of articles on the internet, and various forums which express personal opinions about designing an API and much of it isn’t exactly correct. The problem is that there is no one right or wrong way of approaching API design or architecture. There are various formats and authentication protocols. The ones you choose will be based on your goals and the system for which it is designed.
What Building an API Requires?
During the course of becoming developers ourselves, we had to conduct research, and most of the opinions we came across were only academically sound. Many revolved around using fuzzy logic or something else that was exotic but not practical. So much of this stuff couldn’t be implemented that’s why it is essential that we start with outlining the best practices of API design. Our intention here isn’t to sell you a standard but offering you a streamlined option which you can choose to use. Below are a couple of standards and requirements that APIs should meet:
- The APIs need to use sensible web standards
- It has to be very developer friendly so that developers easily implement it
- It needs to be simple, intuitive, and consistent which will encourage broader adoption
- The API also should be efficient yet at the same time maintain the correct balance between standards and usability
- The API should be both flexible and powerful compatible with various UIs
Note: APIs are meant to be used by developers so it should be backed by excellent support and user experience. Without these variables in place, the API will not succeed at attracting attention.
Should Use SSL Certificates
Developers including ourselves stand behind the use of quality SSL certificates for security purposes. It goes without saying that your web API like all others will be accessed by millions of people through public networks and interfaces which are currently unknown. Since most publically accessible networks aren’t secure or encrypted for that matter, that makes it easier for hackers to gain access, eavesdrop or even impersonate people by forging certificates.
The other reason why we advise that you use SSL certificates is that it will encrypt all the communication and make authentication smoother. So, you can easily get away with using simple access tokens and not having to file each request with the needed API.
Which APIs have to handle non-SSL access? You certainly don’t want any direct requests, and so many requests that may come directly should be redirected with an error message. Also, developers should only send you well-configured requests.
We think that APIs are only as good as their documentation. These documents will make it easier for developers to understand how it is implemented in their programs. Developers today will always check for documentation before even considering an API. So, the documents shouldn’t be hard to reach or require mandatory signing in or some other form of authentication. At best it should be a Wiki.
Once an API goes public, you sort of relinquish control of it. There is no way to change it or update it. So, make sure you get things right from the very beginning.