Ok, you need to build an API. API’s, like snowflakes and people, come in all different shapes and sizes. They do different things, communicate in different ways, and are designed with a variety of approaches and objectives. We have to figure out what your API end game is before we get into the nitty-gritty of building it. To do that, it’s time to answer some questions and consider some preliminary thoughts. Hopefully these are issues you’re already thinking about. If not, no time like the present.
Pick your poison: public, private, or SOA
Each one has its own considerations and needs.
Several issues come into play when deciding what type of API you need. How much control do you want over your brand? How many people are going to be using the API? What’s your current plan for authentication? Are you helping services interact with each other, or connecting a back-end to a front-end? There are lots of different approaches, and they all yield different products.
Public APIs are generally used as platforms, opening up your data and software to outside use. For example, Facebook, Twitter, and Wordpress all have public APIs open to developers. Private APIs, on the other hand, are never seen by the consumer. For example, most mobile applications are built using APIs.
Then there’s SOAs (service oriented architecture)—which some include in the API category and some keep separate. Unlike a basic API, SOAs help backend services work together. Most SOAs are kept private.
Document or die
Documentation is extremely important for APIs because you could have a team of developers who weren’t involved in building the API taking it and running with it. We handle this through a tool we built to combine testing with automatic documentation generation. We’ve published it so you can use it too: check it out in our post [“Curlin’ for Docs.”](/blog/2012/07/12/curlin-for-docs ""cURLin’ for Docs."")
REST, don’t nap
No matter what type of API you’re building, your design should be RESTful (REpresentational State Transfer). Ruby on Rails makes RESTful APIs simple to create. In turn, RESTful design makes APIs simpler to design, version, and use.
Who is the audience?
Is your API for internal use, or will it be publicly available? Will it be a platform that people outside your organization will rely on?
With an API the public uses, you can’t just wander off the map; you have to design with your users in mind. A private API, on the other hand, is essentially like making sure that your handwriting is legible on your kitchen’s whiteboard: it can look like Sanskrit as long as everyone in the house can read it. If the objective is only a communication tool for your team, you have more leeway in designing for you and the team, not developers all over the world.
Thus, your API’s budget and construction will be totally different depending on your ideal use cases.
How’s your budget looking?
If the goal is a private API for internal use, your pockets don’t need to be as deep as a public API project. As explained above, a private API has a focused set of uses and doesn’t need to interface as widely, so building one isn’t as cost intensive.
What’s the lifespan of your API?
In almost all API cases, it makes sense to plan ahead as much as possible, which means designing it right the first time. Especially if your API is used as a platform. When you version your API, it’s extremely important to make each upgrade consistent, reliable, and basically adherent to best practices standards. People who use your API will expect as much, and it makes your life easier down the road.
How will you handle authentication?
In a world of spam and hacking, it’s extremely important to keep your users’ trust. Use OAuth authentication for your API so that external developers don’t have direct access to information like usernames and passwords.
That’s a quick flyby of some things to consider before you get your API on.
Check out our other articles on API:
API Versioning: 3 Ways to Architect Your API to Handle Versioned Requests
API Development: Turning Controller Actions into Services
