10 Ways to Create APIs Developers Will Love

By Darryl K. Taft  |  Posted 2013-12-23 Print this article Print

With the app economy driving jobs and creating revenue, application programming interfaces are more important than ever. Today, every business is a digital business, and APIs power digital business ecosystems. In the API economy—a key component of the app economy—companies expose their business assets or services in the form of APIs to third parties with the goal of unlocking additional business value. Triggered by the explosion of the growth of Internet-enabled devices, the evolution of social interactions and appearance of new software markets in the form of apps, the API economy brings a different philosophy to how companies do business and how they interact with customers and competitors. Forrester Research describes the API economy as: "All commerce generated by the business of providing, consuming, integrating, and adding value to data (and thus often to products and services) via APIs that create economic value." In this new API economy, those without an API strategy will be left behind. This eWEEK slide show, created with input from Brian Mulloy, vice president of Apigee Labs (an API management company), lists 10 tips for building APIs.

  • 10 Ways to Create APIs Developers Will Love

    by Darryl K. Taft
    1 - 10 Ways to Create APIs Developers Will Love
  • Approach API Design From the 'Outside-In' Perspective

    Start by asking, what are we trying to achieve with an API? The API's job is to make the developer as successful as possible. Why? Because the application developer is the lynchpin of the entire API strategy. The primary design principle when crafting your API should be to maximize developer productivity and success.
    2 - Approach API Design From the 'Outside-In' Perspective
  • Keep Simple Things Simple

    The base URL is the most important design affordance of your API. Therefore, a simple, intuitive base URL design makes using your API easy. To keep things simple, use a maximum of two base URLs per resource, keep verbs out of your base URLs, and use HTTP verbs to operate on the collections and elements.
    GET /dogs/1234
    3 - Keep Simple Things Simple
  • Recognize That Good Error Design Is Important

    When designing a new API, we might not be thinking about crafting clear error messages, but errors are the primary way that people will learn how your API works. From the perspective of the developer consuming your Web API, everything at the other side of that interface is a black box. Therefore, errors become a key tool in providing context and visibility into how to use an API.
    4 - Recognize That Good Error Design Is Important
  • Never Release an API Without a Version

    And make the version mandatory. Versioning is one of the most important considerations when designing your Web API. Specify the version with a "v" prefix, move it to the far left in the URL so that it has the highest scope, and use a simple ordinal number such as v1 or v2, rather than the dot notation like v1.2, which implies a granularity of versioning that doesn’t work with APIs.
    Example request to get a dog from a versioned API:
    GET /v1/dogs/1234
    5 - Never Release an API Without a Version
  • Support Partial Response

    APIs that use partial response are simple to read and allow the developer to select just the information an app needs at a given time. Partial response also cuts down on bandwidth issues, which is important for mobile apps. You can support partial response by adding optional fields in a comma delimited list.
    Example request to get just the name and locations fields for a dog:
    GET /v1/dogs/1234?fields=location,name
    6 - Support Partial Response
  • Support Multiple Formats

    Push things out in more than one format and accept as many formats as necessary. You can usually automate the mapping from format to format. We recommend using JSON (JavaScript Object Notation) as your default format, as it's the closest thing to universal language. It also has the advantage of being less verbose than XML.
    Example request to get just an XML version of a dog:
    GET /v1/dogs/1234.json
    7 - Support Multiple Formats
  • Consolidate All API Requests Under One API Subdomain

    It's cleaner, easier and more intuitive for developers whom you want to build cool apps using your API. Your API gateway should be the top-level domain.
    Example of a good API domain:
    8 - Consolidate All API Requests Under One API Subdomain
  • Mitigate the 'Chattiness' of APIs

    API designs that focus on solid resource design are the easiest to learn. However, they are usually "chatty"—meaning that just to build a simple user interface or app, the app will make dozens or hundreds of API calls back to the server. To reduce chattiness and make your API valuable for multiple devices, it’s a good idea to create shortcuts on top of the fundamental resources. Creating a layer of shortcuts is easy once you adhere to the API facade pattern (Tip #10).
    9 - Mitigate the 'Chattiness' of APIs
  • Complement With an SDK

    A common question for API providers: Do you need to complement your API with code libraries and software development kits (SDK)? When doing so, you don't overburden your API design. The SDK can provide the platform-specific code, which developers use in their apps to invoke API operations—meaning you keep your API clean. You might also consider complementing your API with code libraries and SDK because of the simplified integration effort required to work with your API and the reduction of bad or inefficient code.
    10 - Complement With an SDK
  • Implement the API Facade Pattern

    This pattern gives you a buffer or virtual layer between the interface on top and the API implementation on the bottom. You essentially create a facade—a comprehensive view of what the API should be—that is important from the perspective of the app developer and end user of the apps they create.
    11 - Implement the API Facade Pattern

Submit a Comment

Loading Comments...
Manage your Newsletters: Login   Register My Newsletters

Thanks for your registration, follow us on our social networks to keep up-to-date
Rocket Fuel