REST API URL structure

Question

I'm building an application in which there are jobs and each job has some emails sent corresponding to it.

I've got the following URL structure

GET /jobs    # Get all the jobs
GET /jobs/{jobId}   # Get a job by ID
GET /jobs/{jobId}/emails   # Get all emails corresponding to given job ID

POST /jobs  # Create a job
PUT /jobs/{jobId}   # To Create/update a particular job by ID
POST /jobs/_search   # To get a large number of jobs with job IDs in the request body

Now my question is, what should be the URL to get all the emails for a given list of job IDs?

For example. I use GET /jobs to get a list of jobs which contains the job IDs in it. Now I would like to get all the emails for the list of job IDs.

Is it a correct REST structure to use

POST /jobs/emails/_search    # To get all emails corresponding to each job ID in the request body
POST /jobs/emails/_count    # To get the counts of emails corresponding to each job ID in the request body

Or should it be just

POST /emails/_search
POST /emails/_count

Or whether both the patterns are wrong? The first syntax seems correct to me because emails cannot exist without jobs.

The POST search syntax to get multiple resources is taken from this SO answer. The underscores are inspired by the elasticsearch api.

Any help is greatly appreciated. Thanks!

score 2 · Accepted Answer · edited Oct 07 '21 at 11:04

Now my question is, what should be the URL to get all the emails for a given list of job IDs?

REST doesn't care what spelling you use for your identifiers. If your API is hypertext driven, then clients are just following whatever links are provided by the server.

Therefore, in a REST API, the hackable URI style is optional.

Using POST for queries isn't optimal; it's not wrong, but it fails to describe that the query operation is safe, which can be useful information for the client to have when message transport is unreliable.

It would be more common to encode the job ids into the URI in some way. On the web, this is usually done by putting them in the query part of the URI. It is acceptable to put them into one of the path segments instead. You'll probably want to review your implementation's support for URI Templates.

Thanks for your answer. I was going to use comma-separated job IDs in the `GET` call for retrieving email details. But the problem with this is that there is a limitation on the number of characters in the URL. So the `GET` call cannot be used if there are a large no.of job IDs. That is the reason I chose `POST` with search endpoint. — Prashanth, Apr 20 '18 at 11:41

REST API URL structure

1 Answers1