A language for describing resource-oriented APIs & turning them into Swagger or resource diagrams. Oriented around the concepts we want to expose in the APIs.
Apache License 2.0
23
stars
7
forks
source link
Default 404 errors do not cover parent resources as well #31
When defining GET/PUT/PATCH/DELETE operations on a sub-resource, 404 errors are automatically generated in the swagger spec, like follows:
reslang:
subresource Audience::Field {
id: long
/operations
GET
}
auto-generated swagger:
'/v1/audiences/{audienceId}/fields/{id}':
get:
...
responses:
...
'404':
description: Field not found
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
The issue is that the description for this error makes it very specific to only the Field subresource. If the parent resource (Audience in this example) with id {audienceId} cannot be found, then a 404 error with the description Field not found wouldn't make much sense. Maybe we could change the description to something more generic like Resource not found?
Another issue with this is that for other operations like MULTIGET or POST on a subresource, which do not involve finding a single existing instance of that subresource, those operations still need to find an existing parent resource in order to execute successfully.
For example, the POST operation on the Field subresource has the following route: /v1/audiences/{audienceId}/fields. If the parent Audience resource with id {audienceId} cannot be found, then we would still want to return a 404 error. Perhaps reslang should autogenerate these 404 errors for the parent resources for these types of operations?
When defining GET/PUT/PATCH/DELETE operations on a sub-resource, 404 errors are automatically generated in the swagger spec, like follows:
reslang:
auto-generated swagger:
The issue is that the description for this error makes it very specific to only the Field subresource. If the parent resource (Audience in this example) with id
{audienceId}
cannot be found, then a 404 error with the descriptionField not found
wouldn't make much sense. Maybe we could change the description to something more generic likeResource not found
?Another issue with this is that for other operations like MULTIGET or POST on a subresource, which do not involve finding a single existing instance of that subresource, those operations still need to find an existing parent resource in order to execute successfully. For example, the POST operation on the Field subresource has the following route:
/v1/audiences/{audienceId}/fields
. If the parent Audience resource with id{audienceId}
cannot be found, then we would still want to return a 404 error. Perhaps reslang should autogenerate these 404 errors for the parent resources for these types of operations?