Rest API and resources validation from QA perspective

Question

In the current project, let "toys" be the category and "gun" be the product. The ID for the toys category is 2 and ID for the gun product is 1.

The URI for categories is /api/v1/categories/<category_id>.

The URI for products is /api/v1/product/<product_id>.

So we have the category toys at: /api/v1/categories/2 and we have the product gun at: /api/v1/product/1

For deleting a specific product, we have to make a DELETE request to the specific product URI, e.g. DELETE /api/v1/product/1.

But for creating the product, we have to go to /api/v1/product/2 and create a product with a name, and price, and the product resource ID (2 in the given URI) is actually the category ID.

So in this example, if I use .../product/2, then the product is created under the toys category as toys is the category with ID 2.

But I raised an objection and recommended that to create a toy under a category then the POST action should be under that category. In this example, for creating the product, we have to go to /api/v1/categories/2 and create a product with a name, and price and the product will be created in the toys category.

But the developer insists that the implementation is correct, and it is a REST API and so the HATEOS for creating a product will be pointing to the /api/v1/product/<category_id> so there is no need to do this under category resource itself.

As a QA what should be our response to such a design ?

Should it be ignored or are there are any good practices QA follows to ensure the quality of a REST endpoint?

What would be a good checklist for REST API validation ?

Answer 1

Just to add one more explanation.

In REST API, the / indicates a hierarchical relationship between resources. This one rule is already broken when you send a POST req to /api/v1/product/2 and 2 means a category id. Category is not hierarchically under products.

In this example, what category a product belongs to should go into the request body:

{
    categoryId: 2
    ...
}

I'd also stick to proper naming like /api/v1/products and then a concrete one product would be /api/v1/products/1.

REST APIs are also very flexible in a way that rules are not really rules, you can do a lot of things that do not make much sense (especially if the API grows in the number of endpoints etc.).

If this is a new API, I'd press for changing this, if it's some legacy API historically handled by a large number of devs when today no one really knows what they are dealing with, it might be much more difficult to change it.

Answer 2

As QA you are correctly getting a weird feeling. REST aims to do CRUD on resources in a standardized way. By adhering to that standard, you decrease the mental load on the next developer trying to figure out how the application works. Making exceptions to the standard would increase technical debt.

So this issue needs to be addressed and if the one person says "it's fine", address it in the team. Research and present what the standard is for and when it is valid to deviate from the standard.

If the team as a whole is fine with making exceptions.. I guess you have to accept that and focus on other aspects of the API. If you see the problem getting worse, bring it up again at a later point.

Answer 3

As a QA what should be our response to such a design ?

We should poin developers into right direction.

Should it be ignored or are there are any good practices QA follows to ensure the quality of a REST endpoint?

We should be compliant with HTTP protocol, REST dissertaion from Roy Fielding and making sure that REST API is readable, testable and well documented.

What would be a good checklist for REST API validation ?

1. Is it following HTTP Protocol standard (GET is idempotent, POST creates resource, DELETE actually deletes the resource)
2. Does it have good documentation (such as OpenApi 3.0)
3. Naming endpoints (names should be self-explanatory). Please see image below.
4. HTTP Response codes are used properly (200 - OK, 201 - Created!, 400 - Bad Request, 500 - Server error, and so on...). Please refer to RFC 2616 - HTTP Protocol

---

And last but not least, your devs are wrong when come to naming.

This is how the endpoint should be named (let's say we have 'user' resource):