Reading Time: 13 minutes

This is part one of the API design best practices series.

Understand WHY you are building an API

Perhaps the foundation of the foundation, understanding why you are building an API is a crucial step towards understanding what data/ methods your API should make accessible and how your users will utilize it. Unfortunately, API is a buzzword right now, and many companies are rushing to build APIs with the idea that “we’re going to make our data accessible and our users will love it!” There’s probably some truth to that, but that is not a good enough reason. What exactly are you making accessible and why? Who are your API users – are they your customers, or third party services, or developers who are looking to extend upon your application for their customers? Understanding the market you are serving is vital to the success of any product or service.

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

Key questions to ask:

  • Who is our target user for this API
  • Which of our products/ services do we want them to be working with? 
  • What are THEIR use cases for integrating with our API?
  • What technologies will they be using to integrate with our API?
  • What other services will they want our API to interact with?

List out the user FUNCTIONALITY of your API

Once you understand WHY you are building your API, it’s important to list out what your API needs to do, or create user stories that describe in detail the different actions required.  At this juncture you shouldn’t be focused on things like GET, POST, PUT, DELETE; but rather stating that you need to be able to create a user, edit a user, change a password, reset a password, view profile.  Or in the case of an email system be able to create an email, read an email, create a draft, send a draft, move to a folder, delete, get contacts, etc.

By building out the full list of functionality required and by creating these user stories you can see exactly how your users will be using your API, and how your API needs to work together.  You can also involve customers at this point and ask them what features are important to them, allowing you to prioritize them or even find cases that you didn’t consider before.  Remember, it’s ok at this stage to have overlapping actions or duplicate items in your list, such as having “message user” and “send a message,” or “add product to cart” and “add product.”  This will help you ensure that you are considering all of the actions the users will want to be able to do (or that you want them to be allowed to do), while helping you better understand where each action belongs, as well as how it should interact with other resources (“message a user,” for example, should probably go into the messages resource, but should still be linked to via hypertext links in the “get user” response).

Understand what TYPE of API you are building

Among the buzzwords of buzzwords is “REST,” or Representational State Transfer.  However, most APIs are not truly REST or RESTful APIs.  Instead they tend to follow some REST ideals or be JSON-RPC.  It’s important to understand that a key constraint of REST is hypermedia, and that while you may disagree, Dr. Roy Fielding who created the theory of REST remains adamant about this.

The good news is your API doesn’t have to be REST, it could be JSON-RPC, or even SOAP… depending on what your customers need.  If all of your clients are using legacy systems that depend on SOAP libraries, it may make more sense in that case to build a SOAP API for them.  If you are building for simplicity, JSON-RPC couldn’t get easier.  However, if you are building for today’s standards and longevity, REST is a clear winner.  The question becomes what type of API meets your needs best, and it is important to understand which format you are using, especially as you have to make tough decisions in the design process.

Take a look at this quick breakdown to show you some of the advantages and disadvantages of each format, but again remember, it comes down to meeting your users’ needs. 

Think LONG TERM… like 2-3 years down the road

Don’t build your API for today’s product or software roadmap unless you intend to throw it away fairly quickly.  Like building an application it is important to keep your API standardized and extensible.  It’s easy to want to add “quick fixes” to make customers happy, but everything you do should be carefully thought out in order to make sure your API continues to serve not only your needs, but also your clients.

Remember, when you create an API you are creating a contract- your users are depending on your API not just to make their application work, but in order to make a living and feed their families.  When you break things, or when you break backwards compatibility you are taking their time and resources to fix their application instead of adding features and keeping their customers happy.

The industry solution to this has been versioning, however, versioning is merely a Band-Aid, a temporary solution to make migration to the new system less stressful for your clients, but increasingly difficult on you.  Keep in mind, when you have multiple versions of your API you end up supporting and maintaining those versions.  One of the greatest challenges in regards to versioning is getting developers to migrate from one version to another, all while keeping your support staff from going insane.

This doesn’t mean that you shouldn’t plan for versioning.  Rather it means that you should plan to incorporate a version identifier (either in the URI or in the content-header of the response), but work under the mindset that you will only version your API if…

  • You have backwards incompatible PLATFORM changes – in other words you completely change the UI or way your platform works
  • You find that your API is no longer extendable – which is exactly what we are trying to avoid here
  • You find that your spec no longer meets your developer’s needs – for example, they are demanding REST instead of SOAP
You should NOT version your API just because:

 

  • You added additional endpoints
  • You added additional data in the response
  • You changed technologies – your API should be decoupled from your technology stack
  • You changed your applications services or code – your API should be decoupled from your service layer

To clarify on the last two, it shouldn’t matter what technologies you are using, or how your services work.  The API should interact with both, but be decoupled enough that changing something in the background does not effect the API adversely.  Any changes you make to your API in regards to the technology or service layer should be as seamless and transparent as possible.  After all, the less you can break backwards compatibility, the happier you, and your customers will be.  And this can only happen if you go into building your API with a long-term, flexibility, and extensibility focus.

Go to Part 2: Spec Driven Development →

  • Spec Driven Development
  • API Mocking and Prototyping
  • Incorporating User Feedback
  • The API Design Cycle

  
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.