Application Programming Interfaces (APIs) may be regarded as the building blocks of software applications. APIs provide a subset of the functionality of a system to an application. An API may be regarded as a set of libraries that allows an application to be used by multiple applications.
Since APIs can be used by multiple applications, it is import for APIs to be well written and concise. APIs should be carefully planned. The following points may be considered when designing APIs:
Authenticating the APIYour API should be called by valid users that are authorized and authenticated.
Caching API resultsYour API should cache the results of API call. This will allow your API to handle requests more quickly, and it will be able to handle more requests per second. Memcache can be used to cache results of API call.
The API architectureRESTFul APIs have less overhead as compared to SOAP based APIs. SOAP based APIs have better support for authentication. They are also better structured then RESTFul APIs.
API documentationYour API should be well documented and easy for users to understand.
API scopeYour API should have a well defined scope. For example will it be used over the internet as a public API or will it be used as private API inside corporate intranet.
Device supportWhen designing your API you should keep in mind the devices that will consume your API. For example smart phones, desktop application, browser based application, server application etc
API output formatWhen designing your API you should keep in mind the format of the output. For example will the output contain user interface related data or just plain data. One popular approach is known as separation of concerns (https://en.wikipedia.org/wiki/Separation_of_concerns). For example separating the backend and frontend logic.
Rate limiting and throttlingYour API should implement rate limiting and throttling to prevent overuse and misuse of the API.
API versioning and backward compatibilityYour API should be carefully versioned. For example if you update your API, then the new version of your API should support API clients that use an older version of your API. Your API should continue to support the old API clients until all the API clients have migrated to the new version of your API.
API pricing and monitoringThe usage of your API should be monitored, so you know who is using your API and how it is being used. You may also charge users for using your API.
Metric for successYou should also decide which metric to use for measuring the success of your API. For example number of API calls per second or monitory earnings from your API. Activities involved in the development of your API, such as research, publication of articles, open source code, participation in online forums etc may also be considered when determining the success of your API.
API Response timeYour API should have a low response time. It should be possible to monitor the API response time and notify the developer if the API response time above average.
API Error HandlingIn case of errors, your API should return a suitable message to the API client. It should also send notification email to the API developer
Estimation of cost involvedYou should also calculate the cost of developing and deploying your API. For example how much time it will take you to produce a usable version of your API. How much of your development time the API takes.
Updating your APIYou should also decide how often to update your API. For example how often should new features be added. You should also keep in mind the backward compatibility of your API, so updating your API should not negatively affect your clients.