I need to learn the basics of APIs

February 11, 2013 3:42 PM

I'm a web developer who is very capable with HTML and CSS, but that's about it. I am fairly comfortable with SQL, but now I need to learn to develop an API. I'd like to read a good book on the subject. Is there such a book? All I can find are things that explain why an API is useful, or things that assume you already know what you're doing in order to build/use an API.
posted by dylan_k to Computers & Internet (11 answers total)

or things that assume you already know what you're doing in order to build/use an API

That's because building an API is sort of an abstract goal, not a concrete specific thing (not to mention building an API and using one are two entirely different things).

What is your concrete goal? What are you trying to build? What technologies are already in play? What languages/frameworks do you know?

The answer to these questions will provide a lot more insight into what your next steps should be!
posted by wrok at 3:51 PM on February 11, 2013 [1 favorite]

Developing an API is a completely different thing from USING an API. Which do you want to do? And what specifically is your goal (as an API is a means to an end, not an end in and of itself). In general, API development requires more experience than using an API. I would't recommend creating an API that others will be using until you're experienced using others' APIs...
posted by primethyme at 3:51 PM on February 11, 2013

Best answer: One of the books that will help is RESTful Web Services by Richardson and Ruby. It gives a great sense of what REST is, how it's the way the web works, and how it means APIs need to work.
posted by wdenton at 4:01 PM on February 11, 2013 [2 favorites]

I'm going to be blunt: until you've consumed enough APIs to understand and agree or disagree with everything in API design for humans, you're not ready to design one. What I would do:

1. Find an API for a service that you're conceptually familiar with (look for a Developers link in the site footer, or check a directory like ProgrammableWeb or APIS.io).
2. Decide what you want to do with said API.
3. Pick a language (I'm partial to Python but Ruby and PHP are popular as well. Stay away from Java unless your target API is SOAP-only).
4. Write code to accomplish (2).
5. Repeat steps 1-4 with different APIs, experiencing the pain of bad design and poor documentation.
6. Write an API for your service.

posted by djb at 4:23 PM on February 11, 2013 [4 favorites]

I recently stumbled across Emergent One, which sounds like it might be up your alley if you just want to make an API to an existing database, or at least get an idea of what such a thing might look like.

But "developing APIs" really is a subset of "developing Web applications", which is a huge topic that is going to require being comfortable with a programming language like Python, PHP, or Ruby to fully explore. Just like you'd design a Web app to be usable by its intended audience, a usable API is going to offer a good experience to developers. Best way to do that? As people have said above: be a programmer who has consumed lots of APIs.

With that in mind, I think these books/websites are good resources.
REST in Practice: Hypermedia and Systems Architecture (Java, .NET, XML)
Designing Hypermedia APIs (language agnostic)
Building Hypermedia APIs with HTML5 and Node (JavaScript)
posted by substars at 4:31 PM on February 11, 2013 [2 favorites]

Saying you want to write an API is like saying you want to write a document. There are certain general things you can say about them (naming conventions for APIs, for example), but in order to get any useful advice, you have to get more specific. What kind of API? For what? Who is the target audience?
posted by It's Never Lurgi at 4:55 PM on February 11, 2013 [1 favorite]

You can practice using a few APIs at the Codecademy API course, which covers YouTube/bitly/NPR and more. You should certainly not try and build your own API without ever experiencing how to use one someone else built.
posted by jacalata at 5:28 PM on February 11, 2013

Given the skill level you describe, I wonder if you'd be better off standing up an HTSQL instance in front of your database. Among other things, it's fair to think of it as a web API construction kit.
posted by Monsieur Caution at 5:50 PM on February 11, 2013

This isn't a book, but there's a great talk on How to Design a Good API and Why It Matters (slides here). The context is different, but much of the message is nevertheless very applicable.
posted by parudox at 7:30 PM on February 11, 2013 [1 favorite]

"API" is a general term in computing. What you're really asking for is advice on working with RESTful JSON APIs. Google for that, and see what comes up. To get a feel for what they're good for, I would recommend first playing around with existing public JSON APIs like Yelp's or a weather API. Sign up for a developer key and read their documentation, then start making some requests. If you are on a Unix system, you can use curl, or you can use jQuery's $.get and $.post methods to make requests from a web page. JavaScript is probably the easiest way for you to start playing around with HTTP requests if you're primarily a front-end developer.
posted by deathpanels at 11:13 PM on February 11, 2013

Lots of good suggestions above, but I would add that I routinely re-read the apigee best practices guide. As I've become more fluent in API design I learn more from this concise guide. It has helped me to know the right questions to ask.
posted by dgran at 6:54 AM on February 12, 2013