Notes on API Modelling

Notes where taken from the book Designing Great Web APIs By James Higginbotham

The goal of API modelling is to translate the product requirements into the beginnings of a high-level API design. API modelling ensures that both developers and end users have their goals met.

1. Actors/ Users/ Participants

The first step is to identify the participants, sometimes called actors, who will interact with the API. Unlike a user interface, an API design must factor in both humans and non-humans who may interact with your API.

2. Activities

Activities are the outcomes that your participants will expect your API to provide. These activities focus on the job to be done, not how to do it.

3. Steps to achieve those Activities

Break activities into steps that a participant will take to achieve their goal. Goals of a participant or actor will depend upon his needs.

For example, A developer or business analysts can require the same information for the database but for different purposes.

You may find that you may be missing some details about how an activity should be performed. This is an indicator that you should involve one or more subject matter experts (SMEs) who can provide greater insight and details into how the system should work. These experts may be business analysts, customers, and/or quality- assurance teams familiar with the requirements.

4. Grouping by resources

Once you have the activities and steps identified, you will begin to see specific business entities emerge. These are your resource candidates that may become actual API resources.

Others may appear to be resources but may instead be activities that will be performed outside of the API itself and therefore won’t become actual API resources.

5. Validation by testing

Once you have an API model defined, you can use the model to validate that it meets the requirements of internal developers, partner or public developers, and the end user. There are three techniques that can help validate your API model:

1. The API walkthrough
2. Use-case validation
3. Business-process diagrams

Examples of Well designed API

1. Spotify API
2. Stripe API
3. Github API