Three Moral Code for Designing WEB API (Security, Stability, Documentation)

Security

There are many methods to Secure your api but two are most widely used. Token-based authentication and OAuth 2 + SSL

Token-based authentication

For most APIs, I prefer a simple token-based authentication, where the token is a random hash assigned to the user and they can reset it at any point if it has been stolen. Allow the token to be passed in through POST or an HTTP header.

OAuth 2 + SSL

Another very good option is OAuth 2 + SSL. You should be using SSL anyway, but OAuth 2 is reasonably simple to implement on the server side, and libraries are available for many common programming languages.

Here are some other important things to keep in mind:

• Whitelisting Functionality. APIs generally allow you to do basic create, read, update, and delete operations on data. But you don’t want to allow these operations for every entity, so make sure each has a whitelist of allowable actions. Make sure, for example, that only authorized users can run commands like /user/delete/{id}. If it doesn’t, then send back an error message such as a 406 Not Acceptable response.
• Protect yourself against Cross-Site Request Forgery (CSRF). If you are allowing session or cookie authentication, you need to make sure that you’re protecting yourself from CSRF attacks.
• Validate access to resources. In every request, you need to verify that a user is in fact allowed access to the specific item they are referencing.

Stability and Consistency

Let's say you have a api http://niisar.com/api/friendlist and it response JSON Data. This seems fine at first. But what happen when you need to modify the format of JSON? Everyone that’s already integrated with you is going to break. Oops.

So do some planning ahead, and version your API from the outset, explicitly incorporating a version number into the URL like http://niisar.com/api/v1/friendlistso that people rely on v1 of API.

Also use inheritance or a shared architecture to reuse the same naming conventions and data handling consistently throughout your API.

Finally, you need to record and publish a changelog to show differences between versions of your API so that users know exactly how to upgrade.

Documentation and Support

Documentation may be boring but if you want anyone to use your API, documentation is essential. You’ve simply got to get this right. It’s the first thing users will see, so in some ways it’s like the gift wrap. Present well, and people are more likely to use your API.

Fortunately, there are number of software tools that facilitate and simplify the task of generating documentation. Or you can write something yourself for your API

But what separates great documentation from adequate documentation is the inclusion of usage examples and, ideally, tutorials. This is what helps the user understand your API and where to start. It orients them and helps them load your API into their brain.

Make sure that API can get up and running with at least a basic implementation of your API, even if it’s just following a tutorial, within a few minutes. I think 15 minutes is a good goal.

Some specific recommendations to ease and facilitate adoption of your API:

• Make sure people can actually use your API and that it works the first time, every time.
• Keep it simple. so that developers only have to learn your API, not your API + 10 obscure new technologies.
• Provide language-specific libraries to interface with your service.
• Simplify any necessary signup.
• Provide excellent support. A big barrier to adoption is lack of support. How will you handle and respond to a bug report? What about unclear documentation? An unsophisticated user? Forums, bug trackers, and email support are fantastic starts, but do make sure that when someone posts a bug, you really address it. Nobody wants to see a ghost town forum or a giant list of bugs that haven’t been addressed