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

So which should you choose for your cool new API? For a long time, REST was thought to be the only appropriate tool for building modern APIs. But in recent years, another tool was added to the toolbox, when Facebook published GraphQL, the philosophy, and framework powering its popular API. More and more tech companies tried GraphQL and adopted it as one of their philosophies for API design. Some built a GraphQL API next to their existing REST API, some replaced their REST API with GraphQL, and even others have ignored the GraphQL trend to focus single-mindedly on their REST API.

But, not only the tech companies are divided. Following the discussions around REST and GraphQL, there seem to be two camps of gurus leading very emotional discussions: “always use the hammer,” one camp proclaims. “NO, always use the screwdriver,” the other camp insists. And for the rest of us? Unfortunately, this situation is confusing, leading to paralysis and indecision about API design.

The intention of the Book on REST & GraphQL is to clear up the confusion and enable you to make your own decision, the decision that is right for your API. By having the necessary criteria for comparison and general properties, strengths, and weaknesses of the approach, you can choose if the hammer or the screwdriver is better suited for your API project.

Once the bigger-picture, architectural design decisions are nailed, frontend design decisions can be handled. 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. 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.

Learn more in the RESTful API Design Book.

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.

Learn more about Swagger and how to use it in the Swagger & OpenAPI 2.0 Quick Guide.