API101

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.