During the architectural design phase, the API description created in phase 1, is refined. First of all, an appropriate architectural style should be chosen, such as GraphQL, REST, RPC or HATEOAS .

These design decisions should be documented by refining and updating the API description. The API description thus becomes an evolving, single source of truth about the current state of the system.

Once the bigger-picture, architectural design decisions are nailed, frontend design decisions can be handled. For the REST architectural style, these design decisions include:

• Resources

• URIs

• Representations

• Parameters

• HTTP methods

• HTTP status codes

• Consistent naming

• Validation

The detailed design decisions are documented by refining the API description. Typically OpenAPI/Swagger or RAML are used as API description languages. In addition to the above design decisions, it should be avoided to reinvent the wheel for common APIs. Instead, published or company-specific API templates should be used. APIs should also be designed as a part of the API portfolio, meaning that the designed API should be consistent with the other APIs in the same portfolio.

Verification: Simulation & Demo App

A simulation should be used at this point to quickly verify the effects of the architectural and detailed design decisions. The following questions might help to verify the design: Is the API still easy to use? Is it still a small, agile and usable API or did we create a monster API? Does this API help us to realize our usage scenarios? Does the API follow the architectural style selected?

Ideally, the changes that are necessary to the API description at this stage are minimal. The API description should become stable.

As part of the verification, the API description can be handed over to pilot consumers, so they can base the design of their API solution, such as their mobile app, on our design. The demo app created in the previous phase can be reused for integration testing of the simulated API.