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?