API101

From API Codex

Welcome to the API Codex! This intro page should help you get started understanding APIs well enough to dive into the more detailed articles found here. The slides for this workshop can be found at http://www.slideshare.net/synedra/api-101-workshop-from-apistrat-conference - the video will be available shortly and we'll link that as well!

What is an API?

Actually, there are lots of things API can refer to. But in the context of this Codex, and for most articles we are very specifically speaking of REST style APIs - web services used in order to interact with a system. API, in this case, means Application Programmatic Interface, but that's more a throwback to when APIs were used exclusively to define transactions between computers. In today's REST API world, the important pieces are that it is an Interface which has a predictable and documented model - so clients can successfully integrate with another system (like Twitter, Facebook, or LinkedIn) to add new functionality to their system.

If you know how phones originally worked, each phone simply had a ringer which was used to contact the switchboard - the phone had a very simple interface and had no concept of other phones. The caller would then give a unique name (phone number) to the switchboard operator and magically, their phone with the very simple interface was connected to a phone in someone else's home. Newer phones work very similarly to this - the phone sends the number to the service, *magic happens*, and then your phone is connected to theirs. This is all an API does in this context - the client asks for an action and gives a unique name, and the server does what's needed to make this happen.

But How do they Work?

In order for an API to be fully functional, it needs to be able to create, read, update and delete resources. This is referred to with the super sexy moniker CRUD. You can read my post about Conversations to see how this can be understood in the context of real life (where your life is like mine and you order iced tea from Starbucks every day!). For a more in depth description about how REST APIs are used, you can read REST Web Services Demystified.

Business Models

Once you've got an idea how these things work, you may want to explore different choices for your Business Model, Use cases for APIs, or articles about the API Economy.

Designing your API

While REST APIs are simple to execute technically, making the right choices when designing your API can make the difference between an API that struggles or fails and one that succeeds spectacularly. Fortunately, the API Codex has a rich set of writings from experts in the field about how to make your API developer friendly and consistent. There are many articles on Hypermedia APIs, which are quite helpful if you want to dig deep - but if you simply want to maximize your learning time when creating your API, check out A Practical Approach to API Design - this ebook isn't free, but it lays out an excellent process for creating your API with your own company goals in mind.

USA
3scale Networks Inc.
450 Townsend St.
San Francisco, CA 94107, USA
+1 (415) 671-6432
Spain
3scale Networks S. L.
C/Napols 187
08018 Barcelona, Spain
+34 93 309 27 86
London
3scale @ TechHub London
76-80 City Rd
London EC1Y 2BJ
United Kingdom
+44 208 123 8406