CODEWITHSUNDEEP
web-servicesapilanguage-agnostic
pedalpete
pedalpete

Reputation: 21536

Recommendations for writing an API

I'm about to write an api and thought I'd find some good recommendations on things to look out for, how to write a good api.

I of course did a google search, but aside from this from Dustin Diaz http://www.dustindiaz.com/api-writing-tips/, I haven't really been able to find good recommendations.

What are things that you wish you had done differently when creating an API? What made the biggest difference.

I assuming I'm going to use oauth.

I'm purposely not providing details of the api, as I'm looking for more general recommendations that will hopefully be useful to a larger number of people.

Upvotes: 13

Views: 8027

Answers (4)

Gangadhar
Gangadhar

Reputation: 10516

Understand how users are going to use your application. If you can able to note down all the usecases of your application then you can implement each usecase as part of API. At the end of the day you will have an API which provides set of usecases that you decided. Further you should able to extend API with expansion of usecases and should be able to maintain backward compatibility.

API implementation for Web services:
Decide which protocol, data formats and authentication you need to use.
Most of the web services implement API with following parameters.

Protocol: HTTP
Dataformat : JSON/XML
Authentication : API key/Oauth

API implementation for libraries and SDK:
Create prototypes which should be frozen through out life.
Expand API by adding extra functions and do not change existing functions prototypes.
Allow users to provide as many inputs they can as arguments to functions. So the application can do its job as user requested to do.

Keep user in mind and API should allow user to use it with minimum effort.

Refer:
An Introduction to APIs : https://zapier.com/learn/apis

Upvotes: 0

Kingsley Mitchell
Kingsley Mitchell

Reputation: 2589

  1. API must be clear Easy to learn Easy to use, even without documentation Hard to misuse Functionality should be easy to explain Names should be largely self-explanatory Names should be consistent: the same word should mean the same thing through the whole API API should be regular, have some symmetry

Credit given to

http://sharismlab.com/blog/2012/07/21/how-to-write-an-api-for-your-web-app/

Upvotes: 0

R.. GitHub STOP HELPING ICE
R.. GitHub STOP HELPING ICE

Reputation: 215221

I don't think the language-agnostic tag is appropriate for this question, and moreover, it needs a specific language tag. Designing a good API requires a consideration of the characteristics and idioms of the language you're working with. Some of the most important considerations:

  • whether memory is managed manually, with RAII, or with garbage collection.
  • support for generic programming, object oriented programming, functional programming, etc. in the language.
  • what type system the language uses.

So the best piece of advice I can offer to your question as it stands (language-agnostic) is not to assume there are language-agnostic universal API design guidelines, and instead get to know the language(s) you're working with and the appropriate idioms.

Upvotes: 1

Swift
Swift

Reputation: 13188

Key points I would recommend you look at:

  • Implement a RESTful interface
  • Offer a variety of data formats (JSON, XML, etc)
  • Make the syntax intuitive and easy to understand
  • Thorough documentation
  • Use proper response codes

Also, here are some links you may find useful:

http://www.slideshare.net/eaton/building-apis-that-rock
http://www.notiondesign.ca/blog/story/how-not-to-build-an-api/
http://blog.apigee.com/category/api_best_practices/
http://blog.isnotworking.com/2007/05/api-design-guidelines.html

Also, this is a great book that may help you get started:

http://www.amazon.com/dp/0596529260/

Upvotes: 20

Related Questions