I will get back to APIs in a moment. For now, let us assume that we were in the car manufacturing business and we would like to build a new car … What would we have to do?

  1. We find out, how the consumer would want to use the new car.
  2. We design the car, so it fits into the portfolio of different models that our company sells – sports cars, vans, and trucks.
  3. We choose the architectural style, i.e. if the car uses a diesel engine, hybrid engine, or a fully electric engine.
  4. We design a blueprint of the car according to the consumer’s needs and wants. We simulate components of the car and build a prototype.
  5. We select the component suppliers of our car parts,
  6. Finally, we configure the assembly line for putting all the car parts together efficiently.

Could work. And what would the corresponding steps be, when building an API?

  1. We find out, how the majority of consumers would want to use the new API.
  2. We design the API, so it fits into the portfolio of different APIs that our company offers.
  3. We choose the architectural style, i.e. if the API applies a REST, RPC or SOAP style.
  4. We design a blueprint of the API using an API description language, such as RAML or Swagger. We simulate the API and build a prototype of the API.
  5. We select the API platform, which provides the reusable building blocks for the APIs.
  6. Finally, we use a generative API methodology to develop APIs efficiently. Of course, you can only use the generative techniques as far as possible, at some point you might still need to write some code.

All too often, we are tempted to jump into action directly. This is especially true, when building something, which is supposed to be as simple as an API.

Having a guideline for building APIs is extremely helpful, especially when building enterprise APIs. Such a guideline can be provided by a methodology, which is tightly connected to the architecture.

If you need to build APIs for the enterprise, you might be interested in my new book on API architecture and API methodology.

Read more …

How to build APIs efficiently?

Also published on Medium.

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.