CODEWITHSUNDEEP
restapiasp.net-web-apirestful-architecture
Burjua
Burjua

Reputation: 12716

RESTful API and real life example

We have a web application (AngularJS and Web API) which has quite a simple functionality - displays a list of jobs and allows users to select and cancel selected jobs.

We are trying to follow RESTful approach with our API, but that's where it gets confusing.

Getting jobs is easy - simple GET: /jobs

How shall we cancel the selected jobs? Bearing in mind that this is the only operation on jobs we need to implement. The easiest and most logical approach (to me) is to send the list of selected jobs IDs to the API (server) and do necessary procedures. But that's not RESTful way.

If we are to do it following RESTful approach it seams that we need to send PATCH request to jobs, with json similar to this: 

PATCH: /jobs
[
    {
      "op": "replace",
      "path": "/jobs/123",
      "status": "cancelled"
    },
    {
      "op": "replace",
      "path": "/jobs/321",
      "status": "cancelled"
    },
]

That will require generating this json on client, then mapping it to some the model on server, parsing "path" property to get the job ID and then do actual cancellation. This seems very convoluted and artificial to me.

What is the general advice on this kind of operation? I'm curious what people do in real life when a lot of operations can't be simply mapped to RESTful resource paradigm.

Thanks!

Upvotes: 1

Views: 5909

Answers (4)

anjali shrivas
anjali shrivas

Reputation: 1

Example 1: Let’s compare it with a real-world example: You go to a restaurant you sit at your table and you choose that you need ABC. You will have your waiter coming up and taking a note of what you want. You tell him that you want ABC. So, you are requesting ABC, the waiter responds back with ABC he gets in the kitchen and serves you the food. In this case, who is your interface in between you and the kitchen is your waiter. It’s his responsibility to carry the request from you to the kitchen, make sure it’s getting done, and you know once it is ready he gets back to you as a response.

Example 2: Another important example that we can relate is travel booking systems. For instance, take Kayak the biggest online site for booking tickets. You enter your destination, once you select dates and click on search, what you get back are the results from different airlines. How is Kayak communicating with all these airlines? There must be some ways that these airlines are actually exposing some level of information to Kayak. That’s all the talking, it’s through API’s

Example 3: Now open UBER and see. Once the site is loaded, it gives you an ability to log in or continue with Facebook and Google. In this case, Google and Facebook are also exposing some level of users’ information. There is an agreement between UBER and Google/Facebook that has already happened. That’s the reason it is letting you sign up with Google/ Facebook.

Upvotes: 0

inf3rno
inf3rno

Reputation: 26139

PUT /jobs{/ids}/status "cancelled"

so for example

PUT /jobs/123,321/status "cancelled"

if you want to cancel multiple jobs. Be aware, that the job id must not contain the comma character.

https://www.rfc-editor.org/rfc/rfc6570#page-25

Upvotes: -2

Chris Simon
Chris Simon

Reputation: 6505

POST for Business Process

POST is often an overlooked solution in this situation. Treating resources as nouns is a useful and common practice in REST, and as such, POST is often mapped to the "CREATE" operation from CRUD semantics - however the HTTP Spec for POST mandates no such thing:

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

  • Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;
  • Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;
  • Creating a new resource that has yet to be identified by the origin server; and
  • Appending data to a resource's existing representation(s).

In your case, you could use:

POST /jobs/123/cancel

and consider it an example of the first option - providing a block of data to a data handling process - and is analogous to html forms using POST to submit the form.

With this technique, you could return the job representation in the body and/or return a 303 See Other status code with the Location set to /jobs/123

Some people complain that this looks 'too RPC' - but there is nothing that is not RESTful about it if you read the spec - and personally I find it much clearer than trying to find an arbitrary mapping from CRUD operations to real business processes.

Ideally, if you are concerned with following the REST spec, the URI for the cancel operation should be provided to the client via a hypermedia link in your job representation. e.g. if you were using HAL, you'd have:

GET /jobs/123
{
    "id": 123,
    "name": "some job name",
    "_links" : {
       "cancel" : {
           "href" : "/jobs/123/cancel"
       },
       "self" : {
           "href" : "/jobs/123"
       }
    }
}

The client could then obtain the href of the "cancel" rel link, and POST to it to effect the cancellation.

Treat Processes as Resources

Another option is, depending on if it makes sense in your domain, to make a 'cancellation' a noun and associate data with it, such as who cancelled it, when it was cancelled etc. - this is especially useful if a job may be cancelled, reopened and cancelled again, as the history of changes could be useful business data, or if the act of cancelling is an asynchronous process that requires tracking the state of the cancellation request over time. With this approach, you could use:

POST /jobs/123/cancellations

which would "create" a job cancellation - you could then have operations like:

GET /jobs/123/cancellations/1

to return the data associated with the cancellation, e.g.

{
    "cancelledBy": "Joe Smith",
    "requestedAt": "2016-09-01T12:43:22Z",
    "status": "in process"
    "completedAt": null
}

and:

GET /jobs/123/cancellations

to return a collection of cancellations that have been applied to the job and their current status.

Upvotes: 6

Darin Dimitrov
Darin Dimitrov

Reputation: 1038790

If by cancelling a job you mean deleting it then you could use the DELETE verb:

DELETE /jobs?ids=123,321,...

If by cancelling a job you mean setting some status field to cancelled then you could use the PATCH verb:

PATCH /jobs
Content-Type: application/json
[ { "id": 123, "status": "cancelled" }, { "id": 321, "status": "cancelled" } ]

Upvotes: 6

Related Questions