New Series: API Design Best Practices

November 6 2014

2 comments 0

By now, you’ve probably already seen the image of the iceberg cross section showing just how many APIs are available out in the world. With over 13,000 public APIs available for use across the web, and hundreds of thousands more being used privately and in-house, the possibilities are endless.

The demand for flexibility and extensibility has driven the development of APIs and tools alike, and in many regards it has never been easier to create an API than it is today with multitudes of frameworks (such as JAX-RS, Apigility, Django REST Framework, Grape), specs (RAML, Swagger, API Blueprint, IO Docs), and tools (API Designer, API Science, APImatic) available.

However, despite the predictability of the demand for APIs, this tidal wave has taken many by surprise. And while many of these tools are designed to encourage best practices, API design seems to be constantly overlooked for development efficiency. The problem is, however, that while this lack of focus on best practices provides for a rapid development framework, it is nothing more than building a house without a solid foundation. No matter how quickly you build the house, or how nice it looks, without a solid foundation it is just a matter of time before the house crumbles to the ground, costing you more time, energy, and resources then it would have to simply build it right the first time.

The good news is that by following best practices, and carefully implementing these standards, while you may increase development time by weeks, you can shave off months to years of development headaches and potentially save thousands to hundreds of thousands of dollars.

Over the next several weeks we’ll cover a number of different, usually overlooked best practices in depth. But development can’t always wait, so if you’re eager, take a quick look at some of today’s most often missed, yet most important API best practices in our ebooks: 7 Steps to Building your API Blueprint and 7 Habits of Effective API and Service Management or check out my presentation from API Strat: 

Go to Part 1: Planning Your API →

  • Understanding WHY you are building your API
  • Creating a Functionality Map of your API
  • Choosing and Understanding what type of API you’re building
  • Having a long-term mindset and planning for the future

Check out the rest of the :

Be sure to follow @MuleDev on Twitter to get the latest API Best Practices posts and developer news.

Follow @MuleSoft on Twitter, Facebook, and LinkedIn for all the latest in integration.


We'd love to hear your opinion on this post


2 Responses to “New Series: API Design Best Practices”

  1. Liked the best practices eBooks, but while they emphasize the need for documentation of various types (all of the developer portal ideas are documentation deliverables), they don’t say anything about bringing a technical writer on board. Even if a startup gets someone on contract part-time to consult for them, it’s better than leaving everything to engineers. I know: I’ve been documenting APIs for 6 years.

    • Joe,
      That’s a really good point – after hearing a lot of great discussion surrounding this post regarding documentation, we’re adding a series on documentation that will start once the API Best Practice series is done 🙂

      – Mike