7

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 ?

  • 1
    No you are correct. Product is product and category is category. The current design is mixing concerns which is a code smell. The return of each api call should only return that type of thing. – John Peters Mar 26 at 4:35
  • \@JohnPeters thank you for the reply. Hope i will be able to communicate this properly with the management – PDHide Mar 26 at 7:38
  • 2
    The category ID should only be in the URL for creating a product if it's a nested resource, POST .../categories/:id/products. I don't think either of you is correct in the current structure: creating a product should be POST .../products with the category ID being in the payload, as it's part of what defines the resource. – jonrsharpe Mar 26 at 8:23
  • If a product is being created it should be Put to product where category id is in payload.. there's no need to overcomplicate – John Peters Mar 26 at 10:31
  • 1
    That feels like a matter for your specific organisation. What feedback do they want from you? What does quality mean here, beyond the API working as documented/intended? You need to agree this as a team, there aren't general answers. – jonrsharpe Mar 26 at 13:35
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.

| improve this answer | |
  • also: if the team is knowingly creating technical debt, you can track it and prioritize it based on the estimated cost. teams should have a intrinsic motivation to pay back technical debt and making the debt issues visible can help motivating people :) – globalworming Jul 1 at 9:48
2

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.

| improve this answer | |
  • is there a documentation or rule taht states this ? – PDHide Oct 1 at 8:10
  • 1
    It's said in the RFC for URIs: ietf.org/rfc/rfc3986.txt, section 1.2.3 – pavelsaman Oct 1 at 8:40
  • Thank you for the link – PDHide Oct 1 at 15:10
1

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):

REST ENDPOINTS

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.