CODEWITHSUNDEEP
restmicroservicesdomain-driven-designapi-designswagger-2.0
Saurabh Chaturvedi
Saurabh Chaturvedi

Reputation: 2166

What will be an apt resource name for REST API endpoints that just extracts data out of some documents?

I'm brainstorming designing a REST API endpoint for a POST request, which extracts data out of some documents which i provide in the payload and stores it in database or some temporary location . Also i need GET and DELETE endpoints for retrieving and deleting extracted data . I am trying to figure out a resource name which justifies the output of this data-extraction process which i believe is extracted data and also complies with REST API conventions of not naming a resource name as a verb but a noun . Going by the REST API conventions , the resource which we are dealing with is only extracted-data . We cannot name it something like POST /extract-data as it becomes a verb . Or something like POST /data-extraction also not qualifies according to me , as it looks more like a process name than a resource . What i believe is that doing a POST request to extract data, i am providing objects/documents as input and in the output all i create is extracted-data, i can GET the extracted-data, and also i can DELETE the extracted-data, making it the resource which i can deal with . So based on my thought process , I think of below endpoints :

(i.) POST /extracted-data

(ii.) GET /extracted-data/{id}

(iii.) DELETE /extracted-data/{id}

Do above endpoints is really a good resource naming for the stated use-case or is there a better way to do it ?

Upvotes: 0

Views: 188

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57307

Remember, REST doesn't care what spelling conventions you use for your resource identifiers, so long as they are consistent with the production rules in RFC 3986.

We cannot name it something like POST /extract-data as it becomes a verb

The spelling of the identifier doesn't matter, because the method token is the "primary source of request semantics"

Because the machines don't care, we have an extra degree of freedom. So we can design the URI to get more of something else that we want. For instance, by aligning it with the name that human beings would use when talking about the resource.

Resources, in the context of REST are generalizations of documents. The world wide web is the reference implementation of the REST architectural style; the interesting resources on the web are "web pages".

Resources aren't "actions", they are web pages that are modified by actions. So you want to choose an identifier that aligns well with the name of the web page/document/resource, rather than choosing an identifier that aligns with the action of the change.

Upvotes: 1

Related Questions