My api has a job resource which contains a state attribute. The state of a job can be "scheduled", "processing" or "done". The jobs state is determined server-side. When a jobs state is "processing" and ETL process is run server-side.
I want the client to be able to triggering an action like "start" which would set the jobs state to "processing" or trigger a "stop" action which would reset the jobs state to "scheduled".
My question here is how should I handle these "custom" action in REST?
I see two possible approaches:
I could create two new endpoint
POST /job/:id/start
POST /job/:id/stop.
I could create one endpoint which take an action query-param.
POST /job/:id?action=start
POST /job/:id?action=stop
I'm not sure which is considered more RESTful, if either?
Additional, I'm not sure what the response code should be? I'm guessing one of the following: 200 (OK), 202 (Accepted), 204 (No content) but not sure which be best. For example, if the api returned a 200 response should the response body contain the job resource with the updated state? Or, should the api just return 204 no content?
REST does not care about business logic, only about resources - so the most RESTful approach would be a PUT to /job/:id where the document sent will contain the new status.
Although technically the "correct" solution (don't tell Roy Fielding) I rather prefer explicit "actions" like /job/:id/start because it allows my resource to return links to those actions to tell the client if the appropriate action is possible or not (a GET to a "stopped" job would contain a link to start that job for example).
On the basis of HTTP status codes I usually return a 204 when I am not interested in the result although in your case a 200 with the updated resource would be correct - only when you e. g. "start" an already started job a 304 Not Modified would be correct from the view of the client as the state wouldn't have changed.
I would chose 202 Accepted if starting a job has no direct effect on the resource because the job will be e. g. queued and only updated later so that the client knows that an async action has been started.
Related
Could someone please explain how Fork from Elsa Workflow works?
I have set up HTTP Endpoint. After that I send HTTP Request and I get HTTP Response in JSON format.
I want to set condition on that response (for example name='John') so that I could display only that row from database.
What Elsa activity should I use? Is Fork activity correct choice or other?
Fork
The Fork activity simply forks workflow execution into multiple branches. When you add this activity, you specify a list of one or more branch names. These branch names will be scheduled as activity outcomes.
For example, if you add a Fork activity with branches Do Some Request and Timeout, the Fork activity will show these branches as outcomes.
When the Fork activity executes, both branches will execute. This enables scenarios where you for example want to wait for some user input or some other job to finish, but not indefinitely: you have a second branch that waits for a timeout event using e.g. the Timer activity.
A sample workflow that describes the usage of the Fork activity in a similar scenario can be found here.
That describes the use case of the Fork activity. But you will want to use the If activity instead.
If
Going back to your use case with the HTTP Request activity and setting a condition, what you want to use instead of Fork is the If activity.
When you connect an If activity to HTTP Request, you will be able to write a JS expression that must evaluate to true or false.
For example, let's say your Send HTTP Request activity performs a GET request on https://reqres.in/api/users/2
Make sure that the Read Content checkbox is ticked.
Also make sure to give your Send HTTP Request activity a name. For example, SendHttpRequest1.
With that in place, you can now write the following JS expression in the Condition field of the If activity:
activities.SendHttpRequest1.ResponseContent().data.first_name == 'Janet'
Note that activities.SendHttpRequest1.ResponseContent() returns an ExpandoObject that represents the received JSON response from the demo API endpoint I used in my example.
I have a subroutine in my Controller
<HttpPost>
Sub Index(Id, varLotsOfData)
'Point B.
'By the time it gets here - all the data has been accepted by server.
What I would like to do it capture the Id of the inbound POST and mark, for example, a database record to say "Id xx is receiving data"
The POST receive can take a long time as there is lots of data.
When execution gets to point B I can mark the record "All data received".
Where can I place this type of "pre-POST completed" code?
I should add - we are receiving the POST data from clients that we do not control - that is, it is most likely a client's server sending the data - not a webbrowser client that we have served up from our webserver.
UPDATE: This is looking more complex than I had imagined.
I'm thinking that a possible solution would be to inspect the worker processes in IIS programatically. Via the IIS Manager you can do this for example - How to use IIS Manager to get Worker Processes (w3wp.exe) details information ?
From your description, you want to display on the client page that the method is executing and you can show also a loading gif, and when the execution completed, you will show a message to the user that the execution is completed.
The answer is simply: use SignalR
here you can find some references
Getting started with signalR 1.x and Mvc4
Creating your first SignalR hub MVC project
Hope this will help you
If I understand your goal correctly, it sounds like HttpRequest.GetBufferlessInputStream might be worth a look. It allows you to begin acting on incoming post data immediately and in "pieces" rather than waiting until the entire post has been received.
An excerpt from Microsoft's documentation:
...provides an alternative to using the InputStream propertywhich waits until the whole request has been received. In contrast, the GetBufferlessInputStream method returns the Stream object immediately. You can use the method to begin processing the entity body before the complete contents of the body have been received and asynchronously read the request entity in chunks. This method can be useful if the request is uploading a large file and you want to begin accessing the file contents before the upload is finished.
So you could grab the beginning of the post, and provided your client-facing page sends the ID towards the beginning of its transmission, you may be able to pull that out. Of course, this would be reading raw byte data which would need to be decoded so you could grab the inbound post's ID. There's also a buffered one that will allow the stream to be read in pieces but will also build a complete request object for processing once it has been completely received.
Create a custom action filter,
Action Filters for executing filtering logic either before or after an action method is called. Action Filters are custom attributes that provide declarative means to add pre-action and post-action behavior to the controller's action methods.
Specifically you'll want to look at the
OnActionExecuted – This method is called after a controller action is executed.
Here are a couple of links:
http://www.infragistics.com/community/blogs/dhananjay_kumar/archive/2016/03/04/how-to-create-a-custom-action-filter-in-asp-net-mvc.aspx
http://www.asp.net/mvc/overview/older-versions-1/controllers-and-routing/understanding-action-filters-vb
Here is a lab, but I think it's C#
http://www.asp.net/mvc/overview/older-versions/hands-on-labs/aspnet-mvc-4-custom-action-filters
When sending a file, e.g. an image, over HTTP to an API, how should the server respond?
Examples:
respond as soon as file is written to disk
respond only when file is written, processed, checksummed, thumbnailed, watermarked etc.
respond as fast as possible with a link to the resource (even if it's a 404 for a few moments afterwards)
add a 'task' endpoint and respond instantly with a task ID to track the progress before data transfer & processing (eventually including path to resource)
Edit: Added one idea from an answer to a similar question: rest api design and workflow to upload images.
The client doesn't know about disks, processing, checksumming, thumbnailing, etc.
The options then are pretty simple. You either want to return the HTTP request as quickly as possible, or you want the client to wait until you know the operation was successful.
If you want the client to wait, return 201 Created. If you want to return as quickly as possible, return 202 Accepted.
Both are acceptable designs. You should let your own requirements dictate which is better for your case. I would say that by default it's a good idea to 'default' to waiting until the HTTP request was guaranteed to be successful, and only use 202 Accepted if that was a specific requirement.
You could also let the client decide with a Prefer header:
Prefer: respond-async, wait=100
See https://www.rfc-editor.org/rfc/rfc7240#section-4.3
I am building a wrapper for a 3rd party api (email suite) inside of a web application, accessible internally and via an own api. The methods take, for example, an email-address and a subscription list as a parameter and return a result code.
So basically I want to:
Define status codes to display different states of success/failure.
For example successes:
new contact created
new contact created AND optin mail sent
new contact created AND coupon sent
existing contact subscribed
existing contact subscribed AND coupon sent
and so on..
All of these cases are basically the category 2xx OK, but have to trigger different user feedback messages, that's why I'm unhappy with using the HTTP status codes. Using pure HTTP status codes doesn't give feedback detailed enough and defining a) additional status codes or b) completely custom status codes feels so random.
So, what is the best practice to go here?
This answer suggests that I should always use the standard HTTP status codes and if they do not apply, my design is wrong. How would I distinguish the difference, without using additional logic and api calls on the client side?
The purpose of HTTP status codes is to convey the status of the HTTP operation - was it successful, unauthorized, pending, misconfigured, whatever. In all your described cases, the requested operation was successful - everything went as planned. So the most likely status code is 200 OK or 201 CREATED for ALL those cases.
Additional domain-specific statuses should not be forcefully hammered into HTTP statuses. Just return an additional field in your response. For example:
POST http://www.example.com/users
{
name : "The User",
email : "email#theuser.com"
}
Response would contain:
201 CREATED
{
status : "Optin mail sent",
timestamp : "...",
...
}
This keeps a cleaner separation of concerns and improves extensibility.
How would I distinguish the difference, without using additional logic and api calls on the client side?
Use meaningful response bodies. The status code is just that. You don't want to create a new HTTP status code for each new combination of results.
So for your first three scenarios:
HTTP/1.1 201 Created
...
{
contact_created: "true",
optin_mail_sent: "true",
coupon_sent: "true",
}
You need some display logic on the client side any way (e.g. from 254 ContactYesOptInNoCouponYes to the appropriate notifications), so the response body seems the most sensible and extensible way possible.
I'm creating a web API based on the new ASP.NET Web API. I'm trying to understand the best way to handle people submitting multiple data-sets at the same time. If they have 100,000 requests it would be nice to let them submit 1,000 at a time.
Let's say I have a create new Contact method in my Contacts Controller:
public string Put(Contact _contact)
{
//add new _contact to repository
repository.Add(_contact);
//return success
}
What's the proper way to allow users to "Batch" submit new contacts? I'm thinking:
public string BatchPut(IEnumerable<Contact> _contacts)
{
foreach (var contact in _contacts)
{
respository.Add(contact);
}
}
Is this a good practice? Will this parse a GET request with a JSON array of Contacts (assuming they are correctly formatted)?
Lastly, any tips on how best to respond to Batch requests? What if 4 out of 300 fail?
Thanks a million!
When you PUT a collection, you are either inserting the whole collection or replacing an existing collection as if it was a single resource. It is very similar to GET, DELETE or POST a collection. It is an atomic operation. Using is as a substitute for individual calls to PUT a contact may not be very RESTfull (but that is really open for debate).
You may want to look at HTTP pipelining and send multiple PutContact requests of the same socket. With each request you can return standard HTTP status for that single request.
I implemented batch updates in the past with SOAP and we encountered a number of unforeseen issues when the system was under load. I suspect you will run into the same issues if you don't pay attention.
For example, the database may timeout in the middle of the batch update and the all hell broke loose in terms of failures, reliability, transactions etc. And the poor client had to figure out what was actually updated and try again.
When there was too many records to update, the HTTP request would time out because we took too long. That opened another can of worms.
Another concern was how much data would we accept during the update? Was 10MB of contacts enough? Perhaps 1MB? Larger buffers has numerous implications in terms of memory usage and security.
Hence my suggestion to look at HTTP pipelining.
Update
My suggestion would to handle batch creation of contacts as an async process. Just assume that a "job" is the same as a "batch create" process. So the service may look as follows:
public class JobService
{
// Post
public void Create(CreateJobRequest job)
{
// 1. Create job in the database with status "pending"
// 2. Save job details to disk (or S3)
// 3. Submit the job to MSMQ (or SQS)
// 4. For 20 seconds, poll the database to see if the job completed
// 5. If the job completed, return 201 with a URI to "Get" method below
// 6. If not, return 202 (aka the request was accepted for processing, but has not completed)
}
// Get
public Job Get(string id)
{
// 1. Fetch the job from the database
// 2. Return the job if it exists or 404
}
}
The background process that consumes stuff from the queue can update the database or alternatively perform a PUT to the service to update the status of Job to running and completed.
You'll need another service to navigate through the data that was just processed, address errors and so forth.
You background process may be need to be tolerant of validation errors. If not, or if your service does validation (assuming you are not doing database calls etc for which response times cannot be guaranteed), you can return a structure like CreateJobResponse that contains enough information for your client to fix the issue and resubmit the request. If you have to do some validation that is time consuming, do it in the background process, mark the job as failed and update the job with the information that will allow a client to fix the errors and resubmit the request. This assumes that the client can do something with the fact that the job failed.
If the Create method breaks the job request into many smaller "jobs" you'll have to deal with the fact that it may not be atomic and pose numerous challenges to monitor whether jobs completed successfully.
A PUT operation is supposed to replace a resource. Normally you do this against a single resource but when doing it against a collection that would mean you replace the original collection with the set of data passed. Not sure if you are meaning to do that but I am assuming you are just updating a subset of the collection in which case a PATCH method would be more appropriate.
Lastly, any tips on how best to respond to Batch requests? What if 4 out of 300 fail?
That is really up to you. There is only a single response so you can send a 200 OK or a 400 Bad Request and put the details in the body.