API Crash Course
As part of our collaboration with Startupbootcamp Berlin, the leading global startup accelerator with a focus on Smart Transportation & Energy, we ran an API Crash Course workshop. The slides are available on SlideShare and embedded at the bottom of this post. In the workshop we introduced the various business benefits of APIs, how these could be leveraged as an organization and gave some examples of successful case studies. In the second part of the workshop, we covered the various stages of the API lifecycle and introduced best practices and tools for each stage. We will publish details related to each of the four stages of the API lifecycle in a 4-part blog post. The remainder of this post is the first part of this series.
The API Lifecycle
We see the API lifecycle as made up of four stages, which an API provider would iterate through several times as part of an API program. The four stages are: Plan/Design, Build/Integrate, Operate/Manage, and Share/Engage.
The underlying thinking is influenced by agile software engineering methodologies such as Scrum, which recommend producing software incrementally and iteratively. The other influencer is the Lean Startup movement, which advises developing minimum viable products (MVP) in short cycles, testing them on the market, then learning and improving on the product. We described both these ideas in the fourth part of our earlier blog post about “The five elements of software engineering for mobile.”
In the concrete case of an API program – with the goal to develop, publish and promote an API – this would recommend a focus on the core features of the API. Once the core features are published, an API provider should constantly review whether the API performs as envisaged and contributes to the organization’s objectives, revising, adding to or adapting the API if necessary. This process is the same for public, partner, or private APIs. We will discuss each stage in more detail in this 4-part blog post series. We start with the Plan/Design stage.
The first and most important question that needs to be answered in the planning stage is “Why an API?” In the earlier blog post series about the Gold Standard for building great APIs, we discussed the importance of being crystal clear about what should be achieved with exposing assets via APIs. For the success of the API and the organization in a broader sense, the objectives of the API program need to be in line with the organization’s overarching strategy and objectives. Only after this has been made clear, we recommend to start designing the API.
Good API design requires an understanding of the potential users of the API, context for the types of usage, and use cases. The iterative approach of the API lifecycle helps to gain and improve understanding of these areas over time. Different industries and users may know or prefer different paradigms, technologies, or data formats. Meeting these preferences increases the potential adoption of the API. These considerations lead to design decisions such as how data or services are exposed via APIs (REST, SOAP, RPC, proprietary etc.) or data format (JSON, XML etc). Another important aspect is how resources are modeled, i.e., how fine- or coarse-grained the data are in the responses of the API. If an API provider does not necessarily follow an API-first approach or if there are legacy systems to be integrated, the internal data structure will likely be unsuitable to be exposed as-is. That means that an intermediary layer of resource modeling will have to be introduced. Here are some good articles: REST API design — Resource Modeling, How to design APIs that last, or an example of the benefits of an API-first design approach. APICodex also has a lot of articles on API design.
Several tools are available to assist in the design process. The most popular are API Blueprint, RAML and Swagger. Each have their strengths, and the API Evangelist Kin Lane described the differences very well in his post API Design: Do You Swagger, Blueprint or RAML? Another good resource is the article on API Design & Testing State of the Art.
These are some of the important aspects to consider related to the Plan/Design stage of the API lifecycle when building an API program.
In the next post we will cover more details related to the Build/Integrate stage.
Below are the slides of the workshop:
Startupbootcamp Demo Day
3scale is the official API Partner of Startupbootcamp Berlin, which is the leading global startup accelerator with a focus on Smart Transportation & Energy. 3scale is sponsoring upcoming Startupbootcamp Demo Day on November 11 in Berlin, as program members present their business ideas to potential investors. If you’re planning to attend, please stop by and say hello!