Typical API Design Goals

1. Clear separation in Content and Transaction API
2. Call on URL must be separate for regular site and API site
3. API site must be divided into two – test and prod
4. API site must be clearly demarked - json, rest and soap (myapplication.com/api/json, myapplication.com /api/rest, myapplication.com /api/soap).
5. Throttling/Rate Limiting for API calls must consider following factors
a. Time of call
b. Number of records per call
c. Number of calls per second using a API key (free and well as paid)
d. Hits per method/function
e. Test or prod API site
f. Content and Transaction API
g. IP address
h. Geographic Location
i. Specific Key may have enhanced SLAs/priority
j. Developer or Enterprise Key
k. Class of Enterprise – Platinum, Gold, Silver
l. Class of developer – MahaGuru, Guru, GuruBhai
m. Read or Write Call
6. API vs normal site traffic prioritization
7. API response caching ( not now but as application grow this should be pluggable)
8. Provision of deprecation of API
9. Versioning of API
10. Full backward compatibility
11. SSL/TCL availability for critical data – password, payment, etc
12. The call from client may be synchronous but internally it must go to queue (logical) and the requests must be served as per throttling priority  Example sfdc custom or enterprise WSDL
13. The outward call from myApplication.com must go to queue (logical) and then served synchronously to client (myApplication.com will make synchronous call). Messages remaining in queue will die after certain amount of time. This time is not configurable by API users but by admins of myApplication.com.  Example salesforce outbound message
14. To access API each developer must register and must be given key which identifies him/her.
15. To access user (normal site user – API should supply user credentials in secure fashion – SSL). Usage of OAuth needs to be explored.
16. Developer Key will be deactivated if not used for certain period of time.
17. If certain key tries to break throttling. First give warning, then deactivate for certain period of time and then deactivate permanently. Three Strike rule.
18. Reporting
a. Track overall API performance
b. Track API performance for each operation
c. Track API performance by developer
d. Track API performance by specific developer customers
e. Track API performance by client IP
f. Report on API usage by individual developer
g. Report on API usage by developer group
h. Report on API usage by specific developer customers
i. Ability to generate reports in multiple (i.e., CSV, PDF and HMTL) formats
j. Ability to integrate with an existing enterprise reporting system
k. API throughput report
l. API routing failure report
m. API utilization report
n. API availability report
o. API usage report
p. API availability report
q. API methods report
r. API response times report
s. API backend latency report
19. Billing & Metering and API integration
a. Support for Developers account
b. Support for Developers’ customers
c. Ability to bill specific API feature/function