I'm designing a small RESTfull API for a media player and encoder. There you can start, pause and stop a stream or recording.
Lets assume the service is idle - theres no encoding activity. Now the client sends a request to the service like
POST media.box/api/stream
action=stop
This obviously has no effect at the server side but the client should be noticed that theres something wrong with the request.
What HTTP status code is the most suitable for this case?
If you feel that that is an error condition, you should consider returning 422 (Unprocessable Entity). It indicates that the request was received, but a semantic error in the request prevented it from being executed.
The other school of thought is that no-op requests like "stop everything!" when nothing is running should just say "Ok! Nothing is running anymore." and return gracefully. You'll have to decide which is right for your API.
Related
I wrote a Node service that takes parameters from a client and puts them into a SOAP request to another (3rd party) service. Lately, when a request is made to my service, the initial response is a 502 Bad Gateway error with a generic HTML block titled "Server Error" (see image). When I submit the same request a second time, the 3rd party responds with a 500 Internal Server error and a message indicating that a request has already been issued for that transaction.
Obviously the initial request made it to the 3rd party somehow, but they say that the 502 error isn't theirs and isn't logged in their system as ever having occurred.
What I'm trying to find out is if the error is somehow coming from my service because of Docker or Azure (or something else I'm not thinking of). The error is so generic that research hasn't yielded anything useful on it. Has anyone encountered this or know what it is?
It turns out that this was an error being thrown by Azure (or so we think) as the result of some faulty error-handling. Part of the response was being parsed incorrectly, which caused the app to stall. It still doesn't explain how the data still got to the other side while this was happening (or why it hit the catch block at all when there was no error in the processing), but if you see a server error returned with this HTML block, check your error-handling code and investigate Azure!
We have a route in our API which (when called) hits another 3rd party API.
e.g.
HTTP-GET /account/1
this returns some data from our database AND from .. say .. a 3rd party api like Auth0/Okta/SalesForce/whatever.
Now, if this 3rd party api call fails for any reason (fails == 4**, 5** or even a 200 OK but the content is some error message) then what error status code should I pass back to the client calling my API?
Initially I was thinking an HTTP-500-Server-Error but ... I'm not so sure now because I can prevent this error from occurring in the server if I return a nice error message back to the client. So then I thought, return an HTTP-200-OK which contains some key/value of the downstream issue/error ... but is this really OK (pun intended). To me, HTTP-200-OK is like the answer returned is really ok.
So i'm not sure what people do in this scenario.
I feel like an HTTP-500 is for errors that occur but haven't really been handled and/or accounted for.
Now, if this 3rd party api call fails for any reason (fails == 4**, 5** or even a 200 OK but the content is some error message) then what error status code should I pass back to the client calling my API?
APIs should be designed from the consumer's perspective. In most of situations, the API consumer wont't care if the request is fulfilled by the server they are firing a request to or by a downstream server.
If the request to the downstream server prevents your server from fulfilling the client request, you could go for 500 or 503. Alternatively you could return some cached data (if you have any) and return a 2xx status code.
I have seen people using the HTTP code 500 as a generic error code for all kind of error cases (server errors, http errors, code exceptions, expected record not found in DB, time-out exceptions etc). However I have also read and heard that this code 500 should only be used in case of errors originating from the application server (JBoss in my case), and NOT application itself i.e. not for code-exceptions or invalid passwords or DB-record-not-found cases. So, when should we return HTTP Status Code 500 from a REST service method?
As described in the HTTP spec:
The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. A user agent SHOULD display any included representation to the user. These response codes are applicable to any request method.
Original: https://greenbytes.de/tech/webdav/rfc7231.html#rfc.section.6.6
Note that from the protocol point of view, it doesn't matter whether it's the application server or something running inside the application server.
I have a REST Service that can be used to control databases, I want to allow calls to Stop & Start the databases, but was wondering what would be the correct Method?
By calling the Stop or Start Operation I am changing the state of the resource so a PUT seems sort of right, but is PATCH better or even POST?
Any suggestions?
Replacing the state of a resource
REST is protocol independent and is a resource-oriented architecture. When implementing REST applications over the HTTP protocol, for example, the resource is identified by the URI and the operation over the resource is expressed by the HTTP method.
PUT is the HTTP method used to replace the state of a resource and the new state of the resource will be expressed in the request payload using, for example, JSON and/or XML.
So you could consider the following design to start/stop a database:
PUT /databases/:id/status HTTP/1.1
Content-Type: application/json
{
"value": "started"
}
PUT /databases/:id/status HTTP/1.1
Content-Type: application/json
{
"value": "stopped"
}
To obtain the state of a resource, use GET:
GET /databases/:id/status HTTP/1.1
Response status codes
You certainly will need to inform your client about the result of the operation. To do it, use the HTTP response status codes.
A few status that might be useful:
200: Use this status to indicate that the request has succeeded.
202: Use this status code to indicate the request has been accepted for processing, but the processing has not been completed.
204: Use this status code to indicate the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.
409: Use this indicates that the request could not be completed due to a conflict with the current state of the target resource.
Jim Webber explains that "HTTP is the application protocol of transferring documents" The transitions of state in your application are a side effect triggered by the document transfer.
Think old fashioned paper driven business office: the boss comes along and drops a TODO message in your inbox, which says "stop the database". As a side effect, you swivel your chair around and initiate the clean shutdown procedure.
Idiomatically, therefore, the representation you are sending to the REST server is that of the TODO message, and you are sending it to either (a) a resource that represents the "inbox" -- ie, a specific collection of TODO messages -- or (b) a resource that represents the TODO document itself.
I have a REST Service that can be used to control databases, I want to allow calls to Stop & Start the databases, but was wondering what would be the correct Method?
By calling the Stop or Start Operation I am changing the state of the resource so a PUT seems sort of right, but is PATCH better or even POST?
Since you are sending a complete message, rather than trying to make a modification to a message that the REST server already knows about, PATCH is not appropriate.
DELETE is also not appropriate - delete is analogous to destroying the TODO message in the inbox.
If the media type that you are using to represent application state at the client is HTML, then the verb you use shall be POST, because HTML doesn't support PUT.
If you are delivering a representation of a single message to a resource that represents a collection, then the verb you use shall be POST, because the semantics of PUT imply "create/overwrite" of a resource, and the semantic you are expressing is append.
If you are delivering a representation of a single message to a resource that represents that message alone (ie: you are doing a create of the message resource), then PUT is preferred to POST. The key idea here is that PUT promises that any side effects on the server are idempotent -- the side effect of successfully delivering N > 0 copies of the message are equivalent to the side effect of delivering exactly 1 copy. Using PUT as the verb shares that promise, not just with the client and server, but also with all of the intermediate connectors along the way.
Your idempotent resources can also support POST, and you can document in your API that the messages received are handled idempotently so that clients will understand, but there's no standardized way to inform the other connectors of this fact.
(Example: think about a form post in a browser. The resource at the server knows that the request can be handled idempotently. You can document in the html itself that hitting the button more than once is safe, but you don't have any way to tell the browser that, so the browser throws up a message to the user saying "re-POST might not be safe, are you sure Y/N?")
In summary, you want your choices of HTTP methods to agree with the uniform interface, so that the client, the server, and all of the components acting on the messages in between have a shared understanding of what's going on.
I've been looking at examples of REST API's like Netflix http://developer.netflix.com/docs/REST_API_Reference#0_59705 and Twitter and they seem to place error messages in the statusText header response instead of the responseText. We're developing an internal RESTful api and I am arguing for sending custom statusText messages and ignoring the responseText.
For the scope of our app, we're returning error 400 when the user has tried doing something they aren't supposed to, and the only error messages that will be updated in the UI for the user will be delivered with 400. I am of the belief that the message should be sent as a modified statusText but one of the engineers (who knows a bit less about REST than me) is arguing for sending it in the responseText.
What's the best way to go?
HTTP defines that you should put a descriptive error message in the response entity body, aka responseText.
statusText is not rendered or processed by any client.
I'd use the status text for the error message type, aka 400 Client Error, and the body for a description of the problem that can be rendered to the user, in whatever the format the client may be able to process.
Edit: Note that since then, a new standardised format exists to communicate in a standard fashion error details back to the client, which you can find at https://www.rfc-editor.org/rfc/rfc7807 and which I would recommend.
I think you're right, the general approach is use the existing error mechanism built into HTTP.
In general, try to map your errors to existing HTTP errors, for example if they request something they don't have permission to, return a 403 error.
If they request something that doesn't exist, return a 404.
Alex
According to the HTTP specification (rfc2616): "HTTP status codes are extensible"
However I don't think that creating new statuses for every different error message is the correct approach:
I would say choose HTTP Status appropriately (HTTP Status Code Definitions) if you can't find any category which matches your requirement create a custom one (but I'm sure you will) and put error messages in the HTTP response body.
Picking appropriate status code for your responses is extremely important as it is a key enabler of self-descriptive messages.
The entity body should be a representation of the resource's state and ideally contain hyperlinks to available next states in your application
Http Status Codes are pretty self explanatory and should be used as such. Returning 200 OK with validation errors is pretty Soap-y and misleading. Any REST Client implementation 4xx and 5xx errors go into a error block and it really depends on case to case basis if you really want to use the response body for non 2xx responses.