Designing our API and Data

Building APIs in Laravel

The first step in any modern API should be the design phase. We should be planning out the API for the problem we are trying to solve, the very reason we are building the API itself. Many people will skip this step as it is quite a manual process that doesn't involve code but more planning and discussions.

We call this process the design-first approach. It is where we focus on the design of the API before we write any code. As I mentioned, not many people follow this approach strictly. Still, it provides several advantages - we can understand the potential pain points within our API early on and discuss how we might solve them. This can be achieved before writing code, so no costly refactors are needed.

Typically we would use something like the OpenAPI specification for this, a modern standard for you to follow that describes your API in detail. It can be written in JSON or YAML, whichever you and your team are more comfortable with. However, often I do not do this. I use my own format, which is a shorthand I find useful.

Let's walk through some use cases and understand what our API would need to provide and cover to fully understand why we are building an API - and what our API should look like. I won't cover the authentication endpoints in this, as they don't need designing - at least not right now.