What does a RESTful API address look like when GETting data for a specific search term?

Question

What is the cleanest way to design a RESTful API that you want to pass search terms to?

For example, I have an endpoint called "Jobs" and a job could either be an inbound or an outbound job. I want to list all outbound jobs.

Usually, I would pass the id to the web url such as /api/jobs/12 for a specific record. What would the URL look like for showing all jobs for a specific type?

Would it be something like /api/jobs/?direction=inbound ? Is this what normal RESTful addresses look like?

I am using Angular $resource and not sure how to set this up. Previously I use something like this to give me back a specific entity:

  return $resource(settings.apiUrl + 'jobs/:id', {id: '@id'}, {
    'update' : { method: 'PUT' },
    'query': {method: 'GET', isArray: false }
  });

Answer 1

First of all, RESTful principles shouldn't be the end-all-be-all when you design your API structure. Instead, focus on making it easy for another developer to consume and don't get tied up too much in RESTfulness. Meeting all of the REST principles is very difficult and most APIs don't.

That said, if your job objects have a direction property, this URL is perfectly fine (and my personally preferred method), and a lot of APIs do it this way:

GET /api/jobs?direction=inbound

If you need to return jobs based on something other than a property of the job object, for example cancelled jobs, this is also very common:

GET /api/jobs/cancelled

Although in this case, I would prefer to add a status property to the job object and instead use:

GET /api/jobs?status=cancelled