The first step when designing any API is to identify the use cases it’s intended to address. Using an e-commerce application as an example, some use cases might include:
- A customer wants to browse for products by category.
- A customer wants to add a product to their shopping cart.
- A store admin wants to list all customers who bought a given product.
Use case discovery is an exercise that should not be left to your technical team alone – everyone who has a stake in the success of your API regardless of their department or company role should be involved.
In reviewing these use cases, specific objects and users begin to emerge, such as:
- Shopping Cart
- Store Admin
These objects are the nouns your API will represent through resource endpoints. In the NARWHL framework, each noun stands alone and is responsible for representing its own state and related information.
You may tempted, for example, to treat something like Categories as just a parameter of Products. This could work, but Categories often carry with them their own set of information, including their name, the total of products they contain, related categories and more. Because they carry so much information, they should be treated as their own resource with products linking to them.
It’s also tempting to over normalize. For example, if you’re representing a Street Address resource, you may debate whether something such as the Country should be a parameter or a resource. If the Country will be expected to carry additional information – such as demographics – it should certainly be a separate resource. Otherwise, it’s likely safe to keep it as a parameter and perhaps enforce its format (i.e. identifying it consistently as “United States” vs. “USA” vs. “US”) through validation. Good use case discovery should help you determine whether to promote a parameter to its own resource.