CRUD Restlet

Technical (archive)
1

I was looking at EHRScape, I should have posted this question there, but the Community-page does not show any communication-means, only adds.

And maybe the question is also generic and are more people thinking about this.

I am wondering about the HTTP-errors, they seem to be used for communicating application-errors.
I think this could be an error.

For example, if you look at the: DELETE /demographics/party/{partyId}

It can return a 404 with explanation: 404 Not found - the specified party was not found (DEMO-6021).

I think this is possible wrong, because on HTTP-level the call was an success, and should therefor return 200, meaning, the request is received and understood, and processed.
In the return-message it should IMHO, if necessary the result and error-message on application level.

Someone thoughts about this?

Thanks
Bert

2

Hi Bert, that’s a REST Web Services convention. REST reuses a lot of the HTTP infrastructure, like methods, status codes, sone headers, etc.

3

I agree, 404 seems the right code for this. Http talks about “resources”: when an internet browser returns a 404 is because the specified resource you are asking for couldn’t be found on the server, which is exactly the same use case Bert said (the resource you are trying to delete was not find on the server).

4

I think the resource which is meant is the method to delete a party. For example if the url to the method is wrong, it should return a 404. Imagine you are writing a client and you check for the 404 or success to return, how easy can you misinterpret the return if you, f.e., are addressing the wrong server. I think, using HTTP-errors for application-errors, how tempting this may be in some situations, is steaming towards hard to find bugs. So a client first wants to check if the HTTP-call succeeded, and then it wants to know how the application responses to the action. It does not want a return value which can be ambiguously saying something about the HTTP-mechanism or the application, what ever is first. If this is the normal behaviour in REST, I think it is a failure, which we should not take over. Bert

5

There are specific errors to wrong method calls, unsupported mime, etc.
As long as the server returns the correct code then there won't be
interpretation errors.

The thing is that as long as a code is returned, you know that the
server is up and has given you a response based on your request. By
the code you can tell you more things.
2xx messages tell you that the request was a success
4xx messages tell you that there was a client error
5xx messages tell you that there was a server error

On your example 404 is correct because your client requested to delete
an non existing resource, which is a client error.

6

The thing is that as long as a code is returned, you know that the
server is up and has given you a response based on your request. By
the code you can tell you more things.
2xx messages tell you that the request was a success
4xx messages tell you that there was a client error
5xx messages tell you that there was a server error

On your example 404 is correct because your client requested to delete
an non existing resource, which is a client error.

What would be the error code for when the client attempts to
call a non-existing service on the server ?

For example: DELET /demographics/party/{partyId}

or

For example: DELETE /demographics/pardy/{partyId}

Karsten

7

Probably 405 'method not allowed' or just return a generic 400 'bad
request'. In either case you know it is your client fault.
Wikipedia is a good start for most common codes. You can see you can
cover a lot of use cases just with the codes on that page.
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

8

Sorry Diego, I disagree with you. There are several reasons for it.
To avoid a repetition of arguments, I leave it

Have a nice day.

Bert

9

Sorry that I come back to this once more. Karsten almost gave a good example, I want to explain my cause on a better but similar example.

The same problem also occurs with a GET. The REST-service from EHRScape returns a 404 when the party is not found, while the service to get the party is found.
GET /demographich/party/{partyid}
In my opinion it should return 200, the application-service to find the party is found, understood the request, so there is no HTTP-error, but the application returns that the party is not found.
This should be expressed in the result, not in the HTTP-status

So this is a better example, suppose the client calls the wrong server with this URL, he probably gets a 404 because the service cannot be found on that server.

So, if you make a REST-service giving back a 404 if the HTTP- runs fine, but the application cannot find something requested, you are giving an ambiguous message to the client, which cannot determine if there was a 404 on HTTP-level or a 404 on application-level.

I cannot imagine that the designers from RESTlet wanted this ambiguity. I think this is wrong.

Another reason why it is wrong to misuse the HTTP-status for communicating application errors is that there can be only one HTTP-status, and an application may want to communicate more errors.
Where do you put those errors? In the result-data?

Third reason for not using HTTP-status for application errors is that there is a limited number of HTTP-statusses, they have a meaning in the technical context of the HTTP-protocol.
Suppose you want to communicate an error for which you cannot find a good HTTP-number, what do you do?

So I think it is wrong to misuse the HTTP-status for communicating application results.

Now I am leaving this subject, thanks Karsten for your support.

Best regards and have a nice day.
Bert

10

Hi Bert,

I think Diego emails are right on spot and can give you some hints about RESTful principles.
Perhaps you should consider that, what you call 'service' is actually the 'application' itself; than details about returned codes wont be that weird anymore. Also, URLs are resource-refs rather than actions - so a bad URL is generally a resource-not-found or a action-not-allowed.
As far as I know, there are already few openEHR-REST-apis out there, all behaving in a similar if not identical way in what regards returned status codes.

Sebastian

11

Thanks Sebastian for your reply. I have spotted some REST-implementations which use the HTTP-status to communicate application-circumstances.

They are mixing the network-layer (HTTP) with the application layer. It is a very old principle and I learned to not do this. I explained why, below.

Here on this list we mainly have to do with implementers of REST, not REST designers. So what you see is that they all do as all do.

I want to take the question to a higher level of REST-architects, but I know they are not very responsive. So that can take some time and pushing.

I let you know. I am not satisfied with the practice I see here.

Best regards
Bert

12

Hi!

I agree with others here that what Bert is seeing (but perhaps not liking) is most likely proper REST behaviour.

HTTP/REST was designed to work a certain way on purpose for particular reasons that can all be found in the (very readable and well explained) dissertation of Roy Fielding, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm As you can see in the HTTP specification (http://www.w3.org/Protocols/rfc2616/rfc2616.html) Fielding was one of its main authors of it.

Traditional REST or HTTP may not fit all applications, tastes or paradigms, it was designed to be resource oriented and gracefully handle change, different clients, multi level caching, etc. It was not designed primarily for channelling application specific remote function/procedure calls (RPC) like e.g. SOAP is often used for nowadays. (SOAP is sometimes referred to as an abuse of HTTP - mostly using HTTP to get around firewalls not because HTTP was a god fit for remote procedure calls.)

There are other ways to use TCP/IP than HTTP if you want an online service to look somewhat like a an API for RPC. But since the usage scenarios of the web and browsers has broadened you can also see new features being added to more recent HTTP versions (or related standards) that are not necessarily RESTful.
Applying representational state transfer (REST) architecture to archetype-based electronic health record systems
Erik Sundvall, Mikael Nyström, Daniel Karlsson, Martin Eneling, Rong Chen and Håkan Örman
BMC Medical Informatics and Decision Making 2013, 13:57
doi:10.1186/1472-6947-13-57
Available free online at: http://www.biomedcentral.com/1472-6947/13/57

The background chapter gives a fairly compact introduction to REST and references to follow up.

13

Hi!

Some more thoughts regarding specific questions:

Another reason why it is wrong to misuse the HTTP-status for communicating
application errors is that there can be only one HTTP-status, and an
application may want to communicate more errors.
Where do you put those errors? In the result-data?

Have a look at chapter "6. Response Status Codes"starting at
https://tools.ietf.org/html/rfc7231#page-47

If you want to send a deeper explanation for an error or (several errors)
to users or developers the specification says:
"The response message will usually contain a representation that explains
the status."
(For example a html-page, a txt-file or a json-document.)

It is not so different from adding error explanations to
standardized/reused Java exceptions when you are programming you just have
even more freedom.

There are good reasons for trying to reuse a few standardized status codes
in HTTP if you can (see Fieldings dissertation etc.) but the codes are
extensible if you really need to invent your own status code.

They are mixing the network-layer (HTTP) with the application layer. It is a very old principle and I learned to not do this. I explained why, below.

Maybe it is your assumption that HTTP is a pure network layer that misleads you?
Maybe the WWW is resembling a giant distributed application/ecosystem
and HTTP is part of it, all layered on top of the network: TCP/IP?

// Erik

P.s.

Feel free to complain to Roy Fielding, IETF et.al. about the design of
HTTP and REST but for your own sake please do read relevant parts of
his dissertation first. He explains the design choices very well :slight_smile:

If you want to fight more fruitful REST-related battles I am sure you
can find many things on the net that claim to be REST but actually do
not fit the intended purpose of REST and many such designs that are
actually not following the REST design patterns. :slight_smile:

14

According to a discussion on StackOverflow, it should be allowed to use HTTP-status to communicate application response.

There is a schema
http://i.stack.imgur.com/whhD1.png

Here is another (maybe better)
https://raw.githubusercontent.com/for-GET/http-decision-diagram/master/httpdd.png

The discussion is here
http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete

There are also conflicting opinions.

But it seems that a big part of the world finds it OK to use HTTP-status-codes to use for application-errors as if a partyId is a resource like an HTML-document.

So a client cannot distinguish between a missing service and a missing representation for an partyId.

If I do this
(GET) http://localhost:8080/oak/demasdaographic/435980543098

(Response generated by Restlet!)

if gives the same result (404) as this
(GET) http://localhost:8080/oak/demographic/435980543098

(404 should be generated by me)

The first error is a not existing service and the second a not found object, but, although completely different from origin and type they have the same message.

I cannot imagine that this is what people want. But it seems that they do.

Instead I have this below:

My question, why isn't this better? The rest community is making an error, aren't they?

Message and Headers
{
description:"Demographic Object :435980543098 is not found."
errorcode:"OBJECT_NOT_FOUND"
}

Status
*200*OK[Show explanation] Loading time:39
Request headers
User-Agent:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36
Content-Type:text/plain; charset=utf-8
Accept:*/*
Accept-Encoding:gzip, deflate, sdch
Accept-Language:en-US,en;q=0.8,nl;q=0.6
Response headers
Content-type:application/json; charset=UTF-8
Content-length:98
Server:Restlet-Framework/2.2.3
Accept-ranges:bytes
Vary:Accept-Charset, Accept-Encoding, Accept-Language, Accept

(attachments)

iebjjihd.png

15

.

That is true, but Restlet already uses 404 for a “method not found”, or an URL which it can not route to a method.
And the community urges me to also use 404 for a completely other purpose.

In this way my client application can not distinguish what happens and cannot proceed in its doing.

What should report to the user?

“Error 404: Or the party (partyId) you are looking for does not exist in the system,
or the URL to the method to find the party is wrong,
or you are addressing the wrong server which does not understand the URL at all”

Can you imaging the customer looking. Maybe I should program the webcam when the message appears, and publish the result on the Internet.

Must be big fun.

Thank you (not) restlet for this

You are right, HTTP is not a network-layer.

But I understood it to be transparent, to the application it serves.

Before I was using SOAP, better error handling, because there was separation between application and protocol errors.

But thanks for your comments.

Time for a drink (or two)

Bert

16

I think you are comparing a not-so-good rest web service with a perfect soap one. I.e. returning a 404 is wrong for ‘method not found’ (I have put already the correct code in this same thread).
Lack of standard codes makes soap WS much more difficult IMHO.

17

Hi Bert, this is not really a matter of agreeing or not, or if it’s good or bad reusing http status codes: is the way REST services work. If you don’t like it, you should use SOAP.

Every REST API out there uses status codes for app info, twitter, google, …

https://dev.twitter.com/overview/api/response-codes

https://developers.google.com/drive/web/handle-errors

This is a really nice guide I use a lot, it helped me to understand the “REST way” of doing things http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Bottom line, it is no good or bad, it is the REST way :slight_smile:

Pablo.

18

thanks, Pablo.

Since Rest is not a standard, it is a matter of agreeing or not. I’m not sure how to proceed. It is not that having it one way or the other is a lot of work to implement. It is just, what seems better. I was often stubborn, Rowing against the general opinion was often to my advantage. I will think it over.

I wish to thank you all for the discussion and the info.

Best regards
Bert.

19

https://developers.google.com/drive/web/handle-errors

This is exactly my point, 404 is for handling errors, someone not being in a hospital-register is not an error. To check if someone is, and he isn't, that is not necessarily an error.
It may even be a good thing, that someone never has been ill in a specific hospital.
The only thing that a computer, without value judgment can say, is that the call iss successful (HTTP-status 200), and the answer is "No, he is not in the register". That is information.

To call an non-existing service, that is an error, and should return 404. That is what Restlet also has implemented.

Bert

20

You are not asking for a person, you are asking the server for a specific document about a patient that does not exist. A server can have records with identifiers 111, 112, 113, etc. which can be about the same patient or not. If you ask the server for a inexistent document identifier it gives you 404. Document identifier doesn’t mean patient identifier.