subject:"CRUD Restlet"

Ok, you are right, but http is a very generic application layer, not to
designed to serve specific application needs, but designed to serve web
servers which only serve documents.
As you know, a web server is a very generic application, which, from the
time Http was designed, was only recource driven.

Maybe the error is that Rest uses a generic application layer which is
defined as a resource driven application layer, but in fact Rest is used as
a service oriented application protocol. I think that an OpenEhr kernel, or
PayPal-service, or many other Rest using applications are also service
oriented, not only resource oriented, and that therefor, a resource
oriented error handling is unable to serve the needs of a service oriented
application.

You could call that misusing http, because it was not designed for that,
but on the other hand, with some new thinking, Http can be used to serve a
service oriented architecture. Or do you not agree with this statement?

By the way, nowhere is written that Rest must use the Http status mechanism
for communicating application needs. It is written that Rest must used http
statuses for http-needs, and Restlet does do that.

best regards
Bert

Op maandag 19 januari 2015 heeft Peter Gummer
peter.gummer at oceaninformatics.com het volgende geschreven:

Bert Verhees wrote:

The point for me is separation of transport layer and application
layer, and each domain has its own errorhandling.

Hi Bert,

HTTP is not a transport layer protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

?The *Hypertext Transfer Protocol* (*HTTP*) is an application protocol
http://en.wikipedia.org/wiki/Application_protocol ?

Thanks for the discussion, though. I?ve learned a lot from it.

Peter

*This e-mail message is intended exclusively for the addressee(s). Please
inform us immediately if you are not the addressee.*
-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/1b88e832/attachment.html

CRUD Restlet

I checked on how the large companies like Google, Amazon, PayPal, github do
it.

They all have a hybrid solution. They all use an own error schema was
verbal terms, sometimes hierarchical, and they all map their errors to the
http numerical status schema.

This means that a query with no result is qualified as a 404 error. However
this seems unlogical to me, is that how the big guys it do. It is the same
error which is fired when you try to call a non existing method. But the
accompanying message is different.

It is difficult for me to qualify a query which has no result as an error.
Have you ever been sick? No? That is a 404 error.

But on the other hand, that is how the big guys do it.

Bert

Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
volgende geschreven:

By the way, nowhere is written that Rest must use the Http status
mechanism for communicating application needs. It is written that Rest must
used http statuses for http-needs, and Restlet does do that.

best regards
Bert

Op maandag 19 januari 2015 heeft Peter Gummer
peter.gummer at oceaninformatics.com
javascript:_e(%7B%7D,'cvml','peter.gummer at oceaninformatics.com'); het
volgende geschreven:

Bert Verhees wrote:

The point for me is separation of transport layer and application
layer, and each domain has its own errorhandling.

Hi Bert,

HTTP is not a transport layer protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

?The *Hypertext Transfer Protocol* (*HTTP*) is an application protocol
http://en.wikipedia.org/wiki/Application_protocol ?

Thanks for the discussion, though. I?ve learned a lot from it.

Peter

*This e-mail message is intended exclusively for the addressee(s). Please
inform us immediately if you are not the addressee.*

CRUD Restlet

I just had some extra information.

A query with no result would have status 200, for example,
/parties/John+Doe.
When an identified resource is queried, and there is no result, than the
404 will be applicable, for example /party/123456

Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
volgende geschreven:

I checked on how the large companies like Google, Amazon, PayPal, github
do it.

They all have a hybrid solution. They all use an own error schema was
verbal terms, sometimes hierarchical, and they all map their errors to the
http numerical status schema.

This means that a query with no result is qualified as a 404 error.
However this seems unlogical to me, is that how the big guys it do. It is
the same error which is fired when you try to call a non existing method.
But the accompanying message is different.

It is difficult for me to qualify a query which has no result as an error.
Have you ever been sick? No? That is a 404 error.

But on the other hand, that is how the big guys do it.

Bert

Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl
javascript:_e(%7B%7D,'cvml','bert.verhees at rosa.nl'); het volgende
geschreven:

By the way, nowhere is written that Rest must use the Http status
mechanism for communicating application needs. It is written that Rest must
used http statuses for http-needs, and Restlet does do that.

best regards
Bert

Op maandag 19 januari 2015 heeft Peter Gummer
peter.gummer at oceaninformatics.com het volgende geschreven:

Bert Verhees wrote:

The point for me is separation of transport layer and application
layer, and each domain has its own errorhandling.

Hi Bert,

HTTP is not a transport layer protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

?The *Hypertext Transfer Protocol* (*HTTP*) is an application protocol
http://en.wikipedia.org/wiki/Application_protocol ?

Thanks for the discussion, though. I?ve learned a lot from it.

Peter

*This e-mail message is intended exclusively for the addressee(s). Please
inform us immediately if you are not the addressee.*

CRUD Restlet

2015-01-19 Thread Isabel Román Martínez

Hi Bert,
Sorry for my bad english.
I think that any aproximation is a viewpoint of a problem and that you 
can solve the same problem from different viewpoints, using different 
paradigms. The problem is to choose the optimal and when you have no 
options that mix differents paradigms to find the optimal way to do 
this... And if you choose a paradigm you should apply it as best as 
possible, been conforming with it principles always that it is possible 
and trying not to mix with others if it is not essential, some times 
this only implies a little rethinking of the solution.

A service oriented viewpoint and a resource oriented viewpoint could 
solve the same problem, you only have to model your solution agree with 
the principles of the selected way, usually one of them is closer to 
your problem and would give you a better solution (more easy to 
implement or more clear) if you chose the correct one, sometimes it 
could be imposible to use only one aproximation and you have to mix them 
(this could produce more complex and prehaps less interoperable 
solutions)...

In this case, if you are using a Rest viewpoint (Rest itself is resource 
oriented) you should be consecuent with this paradigm, so you must query 
for a resource.
In the sample that you use Have you ever been sick? perhaps this is 
not the correct question/query it could be better if you think in GET 
your episodies of sick (where your episodies of sick could be expressed 
as a URL of course: .../isabel/episodies-of-sick
If this resource could not exist, and this is not an error if it is 
not in the server, you could use the code response 204 No Content, for 
example, that means (I copy the RFC)

The server has fulfilled the request but does not need to return an 
entity-body, and might want to return updated
metainformation. The response MAY include new or updated metainformation 
in the form of entity-headers, which if
present SHOULD be associated with the requested variant.
If the client is a user agent, it SHOULD NOT change its document view 
from that which caused the request to be
sent. This response is primarily intended to allow input for actions to 
take place without causing a change to the user
agent?s active document view, although any new or updated 
metainformation SHOULD be applied to the document
currently in the user agent?s active view.
The 204 response MUST NOT include a message-body, and thus is always 
terminated by the first empty line after
the header fields.

As you could see the metainformation could be applied to the document in 
the user agent's active view (so it is clear that he has not been sick 
and this is not an error), the field your previous sick episodies view 
would remain empty for the user...

Or you can consider that this resource always has to exist, so in the 
server the URL .../isabel/episodies-of-sick would return the resource 
representation episodies-of-sickNo one/episodies-of-sick
Of course you have to manage it properly in your server side...

Best Regards
Isabel Rom?n

El 19/01/2015 a las 6:59, Bert Verhees escribi?:
 I checked on how the large companies like Google, Amazon, PayPal, 
 github do it.

 They all have a hybrid solution. They all use an own error schema was 
 verbal terms, sometimes hierarchical, and they all map their errors to 
 the http numerical status schema.

 This means that a query with no result is qualified as a 404 error. 
 However this seems unlogical to me, is that how the big guys it do. It 
 is the same error which is fired when you try to call a non existing 
 method. But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl 
 mailto:bert.verhees at rosa.nl het volgende geschreven:

 Ok, you are right, but http is a very generic application layer,
 not to designed to serve specific application needs, but designed
 to serve web servers which only serve documents.
 As you know, a web server is a very generic application, which,
 from the time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer
 which is defined as a resource driven application layer, but in
 fact Rest is used as a service oriented application protocol. I
 think that an OpenEhr kernel, or PayPal-service, or many other
 Rest using applications are also service oriented, not
 only resource oriented, and that therefor, a resource oriented
 error handling is unable to serve the needs of a service oriented
 application.

 You could call that misusing http, because it was not designed for
 that, but on the other hand, with some new thinking, Http can be
 used to serve a service oriented architecture. Or do you not agree
 with this

CRUD Restlet

Thank, Isabel,

You are right, you and others have put me on the right track, I know now 
how to proceed

best regards
Bert


On 19-01-15 09:07, Isabel Rom?n Mart?nez wrote:
 Hi Bert,
 Sorry for my bad english.
 I think that any aproximation is a viewpoint of a problem and that you 
 can solve the same problem from different viewpoints, using different 
 paradigms. The problem is to choose the optimal and when you have no 
 options that mix differents paradigms to find the optimal way to do 
 this... And if you choose a paradigm you should apply it as best as 
 possible, been conforming with it principles always that it is 
 possible and trying not to mix with others if it is not essential, 
 some times this only implies a little rethinking of the solution.

 A service oriented viewpoint and a resource oriented viewpoint could 
 solve the same problem, you only have to model your solution agree 
 with the principles of the selected way, usually one of them is closer 
 to your problem and would give you a better solution (more easy to 
 implement or more clear) if you chose the correct one, sometimes it 
 could be imposible to use only one aproximation and you have to mix 
 them (this could produce more complex and prehaps less interoperable 
 solutions)...

 In this case, if you are using a Rest viewpoint (Rest itself is 
 resource oriented) you should be consecuent with this paradigm, so you 
 must query for a resource.
 In the sample that you use Have you ever been sick? perhaps this is 
 not the correct question/query it could be better if you think in GET 
 your episodies of sick (where your episodies of sick could be 
 expressed as a URL of course: .../isabel/episodies-of-sick
 If this resource could not exist, and this is not an error if it is 
 not in the server, you could use the code response 204 No Content, 
 for example, that means (I copy the RFC)

 The server has fulfilled the request but does not need to return an 
 entity-body, and might want to return updated
 metainformation. The response MAY include new or updated 
 metainformation in the form of entity-headers, which if
 present SHOULD be associated with the requested variant.
 If the client is a user agent, it SHOULD NOT change its document view 
 from that which caused the request to be
 sent. This response is primarily intended to allow input for actions 
 to take place without causing a change to the user
 agent?s active document view, although any new or updated 
 metainformation SHOULD be applied to the document
 currently in the user agent?s active view.
 The 204 response MUST NOT include a message-body, and thus is always 
 terminated by the first empty line after
 the header fields.

 As you could see the metainformation could be applied to the document 
 in the user agent's active view (so it is clear that he has not been 
 sick and this is not an error), the field your previous sick 
 episodies view would remain empty for the user...

 Or you can consider that this resource always has to exist, so in the 
 server the URL .../isabel/episodies-of-sick would return the resource 
 representation episodies-of-sickNo one/episodies-of-sick
 Of course you have to manage it properly in your server side...

 Best Regards
 Isabel Rom?n

 El 19/01/2015 a las 6:59, Bert Verhees escribi?:
 I checked on how the large companies like Google, Amazon, PayPal, 
 github do it.

 They all have a hybrid solution. They all use an own error schema was 
 verbal terms, sometimes hierarchical, and they all map their errors 
 to the http numerical status schema.

 This means that a query with no result is qualified as a 404 error. 
 However this seems unlogical to me, is that how the big guys it do. 
 It is the same error which is fired when you try to call a non 
 existing method. But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an 
 error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl 
 mailto:bert.verhees at rosa.nl het volgende geschreven:

 Ok, you are right, but http is a very generic application layer,
 not to designed to serve specific application needs, but designed
 to serve web servers which only serve documents.
 As you know, a web server is a very generic application, which,
 from the time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer
 which is defined as a resource driven application layer, but in
 fact Rest is used as a service oriented application protocol. I
 think that an OpenEhr kernel, or PayPal-service, or many other
 Rest using applications are also service oriented, not
 only resource oriented, and that therefor, a resource oriented
 error handling is unable to serve the needs of a service oriented
 application.

CRUD Restlet

2015-01-19 Thread Seref Arikan

I've managed not to respond for some time but this discussion got to a
point where I can't help commenting :)

REST is a fact of the industry, due to whatever mysterious dynamics that
pushes various solutions down our throat as we get old in front of our
computers. So we live with it.

This does not change the fact that trying to push complex shaped objects
through a few holes shaped as a rectangle, circle and a triangle will leave
some parts of those objects broken. Then we have people discussing for ages
what the right verb mapping would be for an operation. If you try to
express an infinite number of API calls and their semantics with a bunch of
HTTP operations and status codes, this is what you get.

REST may make things easy for some use cases, but do complex use cases in
healthcare fall into that category? I should probably look at Erik's
research at one point but my dislike for being forced to express semantics
with a very limited number of some text transfer protocol based concepts
will not go away.

Best regards
Seref

On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl wrote:

I checked on how the large companies like Google, Amazon, PayPal, github
do it.

They all have a hybrid solution. They all use an own error schema was
verbal terms, sometimes hierarchical, and they all map their errors to the
http numerical status schema.

This means that a query with no result is qualified as a 404 error.
However this seems unlogical to me, is that how the big guys it do. It is
the same error which is fired when you try to call a non existing method.
But the accompanying message is different.

It is difficult for me to qualify a query which has no result as an error.
Have you ever been sick? No? That is a 404 error.

But on the other hand, that is how the big guys do it.

Bert

Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
volgende geschreven:

By the way, nowhere is written that Rest must use the Http status
mechanism for communicating application needs. It is written that Rest must
used http statuses for http-needs, and Restlet does do that.

best regards
Bert

Op maandag 19 januari 2015 heeft Peter Gummer
peter.gummer at oceaninformatics.com het volgende geschreven:

Bert Verhees wrote:

The point for me is separation of transport layer and application
layer, and each domain has its own errorhandling.

Hi Bert,

HTTP is not a transport layer protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

?The *Hypertext Transfer Protocol* (*HTTP*) is an application protocol
http://en.wikipedia.org/wiki/Application_protocol ?

Thanks for the discussion, though. I?ve learned a lot from it.

Peter

*This e-mail message is intended exclusively for the addressee(s). Please
inform us immediately if you are not the addressee.*

___
openEHR-technical mailing list
openEHR-technical at lists.openehr.org

http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/a8116c6b/attachment-0001.html

CRUD Restlet

2015-01-19 Thread Diego Boscá

I will just add that if you are making a server you probably want to
take a look and how FHIR does things. They have some pretty cool ideas
for common problems that you can probably reuse (e.g. using atom for
query responses)

2015-01-19 11:25 GMT+01:00 Seref Arikan serefarikan at kurumsalteknoloji.com:
 I've managed not to respond for some time but this discussion got to a point
 where I can't help commenting :)

 REST is a fact of the industry, due to whatever mysterious dynamics that
 pushes various solutions down our throat as we get old in front of our
 computers. So we live with it.

 This does not change the fact that trying to push complex shaped objects
 through a few holes shaped as a rectangle, circle and a triangle will leave
 some parts of those objects broken. Then we have people discussing for ages
 what the right verb mapping would be for an operation. If you try to express
 an infinite number of API calls and their semantics with a bunch of HTTP
 operations and status codes, this is what you get.

 REST may make things easy for some use cases, but do complex use cases in
 healthcare fall into that category? I should probably look at Erik's
 research at one point but my dislike for being forced to express semantics
 with a very limited number of some text transfer protocol based concepts
 will not go away.

 Best regards
 Seref


 On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl wrote:

 I checked on how the large companies like Google, Amazon, PayPal, github
 do it.

 They all have a hybrid solution. They all use an own error schema was
 verbal terms, sometimes hierarchical, and they all map their errors to the
 http numerical status schema.

 This means that a query with no result is qualified as a 404 error.
 However this seems unlogical to me, is that how the big guys it do. It is
 the same error which is fired when you try to call a non existing method.
 But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
 volgende geschreven:

 Ok, you are right, but http is a very generic application layer, not to
 designed to serve specific application needs, but designed to serve web
 servers which only serve documents.
 As you know, a web server is a very generic application, which, from the
 time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer which is
 defined as a resource driven application layer, but in fact Rest is used as
 a service oriented application protocol. I think that an OpenEhr kernel, or
 PayPal-service, or many other Rest using applications are also service
 oriented, not only resource oriented, and that therefor, a resource oriented
 error handling is unable to serve the needs of a service oriented
 application.

 You could call that misusing http, because it was not designed for that,
 but on the other hand, with some new thinking, Http can be used to serve a
 service oriented architecture. Or do you not agree with this statement?

 By the way, nowhere is written that Rest must use the Http status
 mechanism for communicating application needs. It is written that Rest must
 used http statuses for http-needs, and Restlet does do that.

 best regards
 Bert

 Op maandag 19 januari 2015 heeft Peter Gummer
 peter.gummer at oceaninformatics.com het volgende geschreven:

 Bert Verhees wrote:

 The point for me is separation of transport layer and application
 layer, and each domain has its own errorhandling.



 Hi Bert,

 HTTP is not a transport layer protocol:

 http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

 ?The Hypertext Transfer Protocol (HTTP) is an application protocol ?

 Thanks for the discussion, though. I?ve learned a lot from it.

 Peter



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.


 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org

 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org



 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

CRUD Restlet

2015-01-19 Thread Birger Haarbrandt

The medrecord openEHR server is also based on REST and worth looking at. 
There was a lot to learn from for me as the API is pretty neat.

Best,

Birger

Am 19.01.2015 11:29, schrieb Diego Bosc?:
 I will just add that if you are making a server you probably want to
 take a look and how FHIR does things. They have some pretty cool ideas
 for common problems that you can probably reuse (e.g. using atom for
 query responses)

 2015-01-19 11:25 GMT+01:00 Seref Arikan serefarikan at 
 kurumsalteknoloji.com:
 I've managed not to respond for some time but this discussion got to a point
 where I can't help commenting :)

 REST is a fact of the industry, due to whatever mysterious dynamics that
 pushes various solutions down our throat as we get old in front of our
 computers. So we live with it.

 This does not change the fact that trying to push complex shaped objects
 through a few holes shaped as a rectangle, circle and a triangle will leave
 some parts of those objects broken. Then we have people discussing for ages
 what the right verb mapping would be for an operation. If you try to express
 an infinite number of API calls and their semantics with a bunch of HTTP
 operations and status codes, this is what you get.

 REST may make things easy for some use cases, but do complex use cases in
 healthcare fall into that category? I should probably look at Erik's
 research at one point but my dislike for being forced to express semantics
 with a very limited number of some text transfer protocol based concepts
 will not go away.

 Best regards
 Seref


 On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl 
 wrote:
 I checked on how the large companies like Google, Amazon, PayPal, github
 do it.

 They all have a hybrid solution. They all use an own error schema was
 verbal terms, sometimes hierarchical, and they all map their errors to the
 http numerical status schema.

 This means that a query with no result is qualified as a 404 error.
 However this seems unlogical to me, is that how the big guys it do. It is
 the same error which is fired when you try to call a non existing method.
 But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
 volgende geschreven:

 Ok, you are right, but http is a very generic application layer, not to
 designed to serve specific application needs, but designed to serve web
 servers which only serve documents.
 As you know, a web server is a very generic application, which, from the
 time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer which is
 defined as a resource driven application layer, but in fact Rest is used as
 a service oriented application protocol. I think that an OpenEhr kernel, or
 PayPal-service, or many other Rest using applications are also service
 oriented, not only resource oriented, and that therefor, a resource 
 oriented
 error handling is unable to serve the needs of a service oriented
 application.

 You could call that misusing http, because it was not designed for that,
 but on the other hand, with some new thinking, Http can be used to serve a
 service oriented architecture. Or do you not agree with this statement?

 By the way, nowhere is written that Rest must use the Http status
 mechanism for communicating application needs. It is written that Rest must
 used http statuses for http-needs, and Restlet does do that.

 best regards
 Bert

 Op maandag 19 januari 2015 heeft Peter Gummer
 peter.gummer at oceaninformatics.com het volgende geschreven:
 Bert Verhees wrote:

 The point for me is separation of transport layer and application
 layer, and each domain has its own errorhandling.


 Hi Bert,

 HTTP is not a transport layer protocol:

 http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

 ?The Hypertext Transfer Protocol (HTTP) is an application protocol ?

 Thanks for the discussion, though. I?ve learned a lot from it.

 Peter


 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.


 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.


 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org

 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org


 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org
 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org

CRUD Restlet

2015-01-19 Thread Seref Arikan

Birger and Diego,
Thanks for the useful pointers. I'll take these as starting points to see
how healthcare IT embraces REST.

Best regards
Seref

On Mon, Jan 19, 2015 at 10:31 AM, Birger Haarbrandt 
birger.haarbrandt at plri.de wrote:

  The medrecord openEHR server is also based on REST and worth looking at.
 There was a lot to learn from for me as the API is pretty neat.

 Best,

 Birger

 Am 19.01.2015 11:29, schrieb Diego Bosc?:

 I will just add that if you are making a server you probably want to
 take a look and how FHIR does things. They have some pretty cool ideas
 for common problems that you can probably reuse (e.g. using atom for
 query responses)

 2015-01-19 11:25 GMT+01:00 Seref Arikan serefarikan at 
 kurumsalteknoloji.com serefarikan at kurumsalteknoloji.com:

  I've managed not to respond for some time but this discussion got to a point
 where I can't help commenting :)

 REST is a fact of the industry, due to whatever mysterious dynamics that
 pushes various solutions down our throat as we get old in front of our
 computers. So we live with it.

 This does not change the fact that trying to push complex shaped objects
 through a few holes shaped as a rectangle, circle and a triangle will leave
 some parts of those objects broken. Then we have people discussing for ages
 what the right verb mapping would be for an operation. If you try to express
 an infinite number of API calls and their semantics with a bunch of HTTP
 operations and status codes, this is what you get.

 REST may make things easy for some use cases, but do complex use cases in
 healthcare fall into that category? I should probably look at Erik's
 research at one point but my dislike for being forced to express semantics
 with a very limited number of some text transfer protocol based concepts
 will not go away.

 Best regards
 Seref


 On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl 
 bert.verhees at rosa.nl wrote:

  I checked on how the large companies like Google, Amazon, PayPal, github
 do it.

 They all have a hybrid solution. They all use an own error schema was
 verbal terms, sometimes hierarchical, and they all map their errors to the
 http numerical status schema.

 This means that a query with no result is qualified as a 404 error.
 However this seems unlogical to me, is that how the big guys it do. It is
 the same error which is fired when you try to call a non existing method.
 But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl 
 bert.verhees at rosa.nl het
 volgende geschreven:


  Ok, you are right, but http is a very generic application layer, not to
 designed to serve specific application needs, but designed to serve web
 servers which only serve documents.
 As you know, a web server is a very generic application, which, from the
 time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer which is
 defined as a resource driven application layer, but in fact Rest is used as
 a service oriented application protocol. I think that an OpenEhr kernel, or
 PayPal-service, or many other Rest using applications are also service
 oriented, not only resource oriented, and that therefor, a resource oriented
 error handling is unable to serve the needs of a service oriented
 application.

 You could call that misusing http, because it was not designed for that,
 but on the other hand, with some new thinking, Http can be used to serve a
 service oriented architecture. Or do you not agree with this statement?

 By the way, nowhere is written that Rest must use the Http status
 mechanism for communicating application needs. It is written that Rest must
 used http statuses for http-needs, and Restlet does do that.

 best regards
 Bert

 Op maandag 19 januari 2015 heeft Peter Gummerpeter.gummer at 
 oceaninformatics.com peter.gummer at oceaninformatics.com het volgende 
 geschreven:

  Bert Verhees wrote:


  The point for me is separation of transport layer and application
 layer, and each domain has its own errorhandling.



 Hi Bert,

 HTTP is not a transport layer protocol:
 http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

 ?The Hypertext Transfer Protocol (HTTP) is an application protocol ?

 Thanks for the discussion, though. I?ve learned a lot from it.

 Peter



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.


 ___
 openEHR-technical mailing listopenEHR-technical at lists.openehr.org

CRUD Restlet

2015-01-19 Thread Ian McNicoll

Hi all,

I agree with Diego -stay close to FHIR, if only because it will reduce
the burden on developers. I think there are some discussions about
dropping atom for bundles though.

As well as the Medvision360 api that Birger has pointed to, the crews
at Code24 and Ocean/ Lockheed Martin have partially cloned the
Ehrscape API, related to the NHS Code4Health project with which I am
involved.

See
https://github.com/handihealth/C4H_dental_challenge/blob/master/README.md#openehr-connectathon-ehrscape-api-endpoints

We did not actually get around to doing a connectathon on the day
(long story!) but it would be interesting to know how people felt
about starting to coalesce an openEHR REST-based service layer, based
on the Ehrscape API.

As Erik posted earlier, the ability to show cross-platfrom working is
hugely important.

Ian
Ian

Dr Ian McNicoll
office +44 (0)1536 414 994
fax +44 (0)1536 516317
mobile +44 (0)775 209 7859
skype ianmcnicoll
ian.mcnicoll at oceaninformatics.com

Clinical Modelling Consultant, Ocean Informatics, UK
Director openEHR Foundation www.openehr.org/knowledge
Honorary Senior Research Associate, CHIME, UCL
SCIMP Working Group, NHS Scotland
BCS Primary Health Care www.phcsg.org

On 19 January 2015 at 10:31, Birger Haarbrandt
birger.haarbrandt at plri.de wrote:
The medrecord openEHR server is also based on REST and worth looking at.
There was a lot to learn from for me as the API is pretty neat.

Best,

Birger

Am 19.01.2015 11:29, schrieb Diego Bosc?:

I will just add that if you are making a server you probably want to
take a look and how FHIR does things. They have some pretty cool ideas
for common problems that you can probably reuse (e.g. using atom for
query responses)

2015-01-19 11:25 GMT+01:00 Seref Arikan serefarikan at
kurumsalteknoloji.com:

I've managed not to respond for some time but this discussion got to a point
where I can't help commenting :)

REST is a fact of the industry, due to whatever mysterious dynamics that
pushes various solutions down our throat as we get old in front of our
computers. So we live with it.

This does not change the fact that trying to push complex shaped objects
through a few holes shaped as a rectangle, circle and a triangle will leave
some parts of those objects broken. Then we have people discussing for ages
what the right verb mapping would be for an operation. If you try to express
an infinite number of API calls and their semantics with a bunch of HTTP
operations and status codes, this is what you get.

Best regards
Seref

On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl wrote:

I checked on how the large companies like Google, Amazon, PayPal, github
do it.

They all have a hybrid solution. They all use an own error schema was
verbal terms, sometimes hierarchical, and they all map their errors to the
http numerical status schema.

This means that a query with no result is qualified as a 404 error.
However this seems unlogical to me, is that how the big guys it do. It is
the same error which is fired when you try to call a non existing method.
But the accompanying message is different.

It is difficult for me to qualify a query which has no result as an error.
Have you ever been sick? No? That is a 404 error.

But on the other hand, that is how the big guys do it.

Bert

Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
volgende geschreven:

Maybe the error is that Rest uses a generic application layer which is
defined as a resource driven application layer, but in fact Rest is used as
a service oriented application protocol. I think that an OpenEhr kernel, or
PayPal-service, or many other Rest using applications are also service
oriented, not only resource oriented, and that therefor, a resource oriented
error handling is unable to serve the needs of a service oriented
application.

By the way, nowhere is written that Rest must use the Http status
mechanism for communicating application needs. It is written that Rest must
used http statuses for http-needs, and Restlet does do that.

best regards
Bert

CRUD Restlet

2015-01-19 Thread Ian McNicoll

Hi Seref,

You are of course correct that FHIR or any other RESTful approaches
may struggle in more complex scenarios but I think there is increasing
evidence that simpler approaches can bring immense benefit and are an
order of magnitude easier to implement for non-specialist developers.

In the UK, FHIR is rapidly becoming the de-facto Industry standard for
GP system interfaces butt here is strong recognition that the clinical
content development/ maintenance is not going to scale, which is why
openEHR has now been picked up (again) by the NHS.

I think the openEHR implementer community has a huge opportunity to
show how it can play very effectively in this emerging space.

Ian
Dr Ian McNicoll
mobile +44 (0)775 209 7859
office +44 (0)1536 414994
skype: ianmcnicoll
email: ian at freshehr.com
twitter: @ianmcnicoll

Director, freshEHR Clinical Informatics
Director, openEHR Foundation
Director, HANDIHealth CIC
Hon. Senior Research Associate, CHIME, UCL


On 19 January 2015 at 10:25, Seref Arikan
serefarikan at kurumsalteknoloji.com wrote:
 I've managed not to respond for some time but this discussion got to a point
 where I can't help commenting :)

 REST is a fact of the industry, due to whatever mysterious dynamics that
 pushes various solutions down our throat as we get old in front of our
 computers. So we live with it.

 This does not change the fact that trying to push complex shaped objects
 through a few holes shaped as a rectangle, circle and a triangle will leave
 some parts of those objects broken. Then we have people discussing for ages
 what the right verb mapping would be for an operation. If you try to express
 an infinite number of API calls and their semantics with a bunch of HTTP
 operations and status codes, this is what you get.

 REST may make things easy for some use cases, but do complex use cases in
 healthcare fall into that category? I should probably look at Erik's
 research at one point but my dislike for being forced to express semantics
 with a very limited number of some text transfer protocol based concepts
 will not go away.

 Best regards
 Seref


 On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl wrote:

 I checked on how the large companies like Google, Amazon, PayPal, github
 do it.

 They all have a hybrid solution. They all use an own error schema was
 verbal terms, sometimes hierarchical, and they all map their errors to the
 http numerical status schema.

 This means that a query with no result is qualified as a 404 error.
 However this seems unlogical to me, is that how the big guys it do. It is
 the same error which is fired when you try to call a non existing method.
 But the accompanying message is different.

 It is difficult for me to qualify a query which has no result as an error.
 Have you ever been sick? No? That is a 404 error.

 But on the other hand, that is how the big guys do it.

 Bert

 Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl het
 volgende geschreven:

 Ok, you are right, but http is a very generic application layer, not to
 designed to serve specific application needs, but designed to serve web
 servers which only serve documents.
 As you know, a web server is a very generic application, which, from the
 time Http was designed, was only recource driven.

 Maybe the error is that Rest uses a generic application layer which is
 defined as a resource driven application layer, but in fact Rest is used as
 a service oriented application protocol. I think that an OpenEhr kernel, or
 PayPal-service, or many other Rest using applications are also service
 oriented, not only resource oriented, and that therefor, a resource oriented
 error handling is unable to serve the needs of a service oriented
 application.

 You could call that misusing http, because it was not designed for that,
 but on the other hand, with some new thinking, Http can be used to serve a
 service oriented architecture. Or do you not agree with this statement?

 By the way, nowhere is written that Rest must use the Http status
 mechanism for communicating application needs. It is written that Rest must
 used http statuses for http-needs, and Restlet does do that.

 best regards
 Bert

 Op maandag 19 januari 2015 heeft Peter Gummer
 peter.gummer at oceaninformatics.com het volgende geschreven:

 Bert Verhees wrote:

 The point for me is separation of transport layer and application
 layer, and each domain has its own errorhandling.



 Hi Bert,

 HTTP is not a transport layer protocol:

 http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

 ?The Hypertext Transfer Protocol (HTTP) is an application protocol ?

 Thanks for the discussion, though. I?ve learned a lot from it.

 Peter



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the addressee.



 --
 This e-mail message is intended exclusively for the addressee(s).
 Please inform us immediately if you are not the

CRUD Restlet

2015-01-19 Thread Gerard Freriks (privé)

Niet een slecht advies: Kijken bij FHIR van HL7

GF

Gerard Freriks
+31 620347088
gfrer at luna.nl mailto:gfrer at luna.nl
 On 19 jan. 2015, at 11:29, Diego Bosc? yampeku at gmail.com wrote:
 
 I will just add that if you are making a server you probably want to
 take a look and how FHIR does things. They have some pretty cool ideas
 for common problems that you can probably reuse (e.g. using atom for
 query responses)

-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/6a442f1d/attachment.html

CRUD Restlet

2015-01-19 Thread Seref Arikan

Hi Ian,
Thanks for the response. Just to clarify: as I've written, REST works for
some simple cases and delivers an economic advantage as you've also
expressed in the form of getting non specialist developers involved.

I for one am happy to see FHIR exploring this, which is apparently
delivering good results. As I've written, we'll leave with REST, it is an
industry standard now for many things. As long as we don't try to push
everything into it, we should be able to see benefits.

Best regards
Seref


On Mon, Jan 19, 2015 at 10:51 AM, Ian McNicoll ian at freshehr.com wrote:

 Hi Seref,

 You are of course correct that FHIR or any other RESTful approaches
 may struggle in more complex scenarios but I think there is increasing
 evidence that simpler approaches can bring immense benefit and are an
 order of magnitude easier to implement for non-specialist developers.

 In the UK, FHIR is rapidly becoming the de-facto Industry standard for
 GP system interfaces butt here is strong recognition that the clinical
 content development/ maintenance is not going to scale, which is why
 openEHR has now been picked up (again) by the NHS.

 I think the openEHR implementer community has a huge opportunity to
 show how it can play very effectively in this emerging space.

 Ian
 Dr Ian McNicoll
 mobile +44 (0)775 209 7859
 office +44 (0)1536 414994
 skype: ianmcnicoll
 email: ian at freshehr.com
 twitter: @ianmcnicoll

 Director, freshEHR Clinical Informatics
 Director, openEHR Foundation
 Director, HANDIHealth CIC
 Hon. Senior Research Associate, CHIME, UCL


 On 19 January 2015 at 10:25, Seref Arikan
 serefarikan at kurumsalteknoloji.com wrote:
  I've managed not to respond for some time but this discussion got to a
 point
  where I can't help commenting :)
 
  REST is a fact of the industry, due to whatever mysterious dynamics that
  pushes various solutions down our throat as we get old in front of our
  computers. So we live with it.
 
  This does not change the fact that trying to push complex shaped objects
  through a few holes shaped as a rectangle, circle and a triangle will
 leave
  some parts of those objects broken. Then we have people discussing for
 ages
  what the right verb mapping would be for an operation. If you try to
 express
  an infinite number of API calls and their semantics with a bunch of HTTP
  operations and status codes, this is what you get.
 
  REST may make things easy for some use cases, but do complex use cases in
  healthcare fall into that category? I should probably look at Erik's
  research at one point but my dislike for being forced to express
 semantics
  with a very limited number of some text transfer protocol based concepts
  will not go away.
 
  Best regards
  Seref
 
 
  On Mon, Jan 19, 2015 at 5:59 AM, Bert Verhees bert.verhees at rosa.nl
 wrote:
 
  I checked on how the large companies like Google, Amazon, PayPal, github
  do it.
 
  They all have a hybrid solution. They all use an own error schema was
  verbal terms, sometimes hierarchical, and they all map their errors to
 the
  http numerical status schema.
 
  This means that a query with no result is qualified as a 404 error.
  However this seems unlogical to me, is that how the big guys it do. It
 is
  the same error which is fired when you try to call a non existing
 method.
  But the accompanying message is different.
 
  It is difficult for me to qualify a query which has no result as an
 error.
  Have you ever been sick? No? That is a 404 error.
 
  But on the other hand, that is how the big guys do it.
 
  Bert
 
  Op maandag 19 januari 2015 heeft Bert Verhees bert.verhees at rosa.nl
 het
  volgende geschreven:
 
  Ok, you are right, but http is a very generic application layer, not to
  designed to serve specific application needs, but designed to serve web
  servers which only serve documents.
  As you know, a web server is a very generic application, which, from
 the
  time Http was designed, was only recource driven.
 
  Maybe the error is that Rest uses a generic application layer which is
  defined as a resource driven application layer, but in fact Rest is
 used as
  a service oriented application protocol. I think that an OpenEhr
 kernel, or
  PayPal-service, or many other Rest using applications are also service
  oriented, not only resource oriented, and that therefor, a resource
 oriented
  error handling is unable to serve the needs of a service oriented
  application.
 
  You could call that misusing http, because it was not designed for
 that,
  but on the other hand, with some new thinking, Http can be used to
 serve a
  service oriented architecture. Or do you not agree with this statement?
 
  By the way, nowhere is written that Rest must use the Http status
  mechanism for communicating application needs. It is written that Rest
 must
  used http statuses for http-needs, and Restlet does do that.
 
  best regards
  Bert
 
  Op maandag 19 januari 2015 heeft Peter Gummer
  peter.gummer at

CRUD Restlet

On 19-01-15 12:06, Gerard Freriks (priv?) wrote:
 Niet een slecht advies: Kijken bij FHIR van HL7

I will check that


 GF

 Gerard Freriks
 +31 620347088
 gfrer at luna.nl mailto:gfrer at luna.nl

 On 19 jan. 2015, at 11:29, Diego Bosc? yampeku at gmail.com 
 mailto:yampeku at gmail.com wrote:

 I will just add that if you are making a server you probably want to
 take a look and how FHIR does things. They have some pretty cool ideas
 for common problems that you can probably reuse (e.g. using atom for
 query responses)



 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/a65aa321/attachment-0001.html

CRUD Restlet

On 19-01-15 11:31, Birger Haarbrandt wrote:
 The medrecord openEHR server is also based on REST and worth looking 
 at. There was a lot to learn from for me as the API is pretty neat.

I will check that too, thanks for the links

Bert

-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/9e1acdc6/attachment.html

CRUD Restlet

Hi,


On 01/19/2015 11:31 AM, Birger Haarbrandt wrote:

 The medrecord openEHR server is also based on REST and worth looking at.
 There was a lot to learn from for me as the API is pretty neat.


Thanks. We do our best to make the REST API of MedRecord as simple as 
possible. We try to base the development of the API on actual usecases 
and what kind of information in needed by (UI) clients without requiring 
the users of our API to have any knowledge about openEHR or know how 
things should work from a medical point of view.


This has lead to our current version of MedRecord (which is still work 
in progress) and can be found here:

https://mr.dev.medvision360.org/mr/apidocs/#!/

(see below if you want to try the API)


Since we want to make it easy for web application to access our APIs, we 
should use whatever technique works best for web applications. Currently 
this means we must use REST over HTTP, HATEOAS, JSON documents, JSON 
schemas and a focus on (good) (API) documentation.

I do think the REST architecture style is better than most SOAP, CORBA 
and ESB solutions and it currently is the best way to access remote 
resources. But doing REST properly is not easy.

The current API of MedRecord consists of two pieces:
A fully automatically generated API based on the ADL files. (everything 
starting with /ehr )
And an API based on procedures (everything starting with /procedure )

The main difference is that the procedure API can be used without any 
knowledge of openEHR. All openEHR difficulties are hidden behind the 
procedure API which should make the API simple enough to be usable by 
any (UI) developer not familiar with openEHR or health care.

These two APIs are different views on the openEHR data stored in a 
database. This also means we can swap the backend which we are currently 
using for any other openEHR backend.

The MedRecord API also comes with Java (and JavaScript) client libraries 
which hides all the REST stuff which makes accessing resources as simple 
a single line of code while providing the data as plain old Java objects.

Also note we have two versions of MedRecord. A version based on XML and 
a version not based on XML.
Our current focus lies on the version without XML and this is the 
version which can be seen in the link above.


Since our API needs authentication, you can test our API if you go to 
the following page:

https://mr.dev.medvision360.org/mr/apidocs/#!/

and use the text helloletmeinplease as authToken parameter.

For example:

https://mr.dev.medvision360.org/mr/ehr?authToken=helloletmeinplease

lists all EHRs currently in our development server.


Btw. this answer might be slightly off-topic but I wanted to explain the 
process of how we developed our current API.


Ralph.

MedVision360



-- 
This e-mail message is intended exclusively for the addressee(s). Please 
inform us immediately if you are not the addressee.

CRUD Restlet

Thanks Ralph

;-)

On 19-01-15 13:10, Ralph van Etten wrote:
 Hi,


 On 01/19/2015 11:31 AM, Birger Haarbrandt wrote:

 The medrecord openEHR server is also based on REST and worth looking at.
 There was a lot to learn from for me as the API is pretty neat.


 Thanks. We do our best to make the REST API of MedRecord as simple as 
 possible. We try to base the development of the API on actual usecases 
 and what kind of information in needed by (UI) clients without 
 requiring the users of our API to have any knowledge about openEHR or 
 know how things should work from a medical point of view.


 This has lead to our current version of MedRecord (which is still work 
 in progress) and can be found here:

 https://mr.dev.medvision360.org/mr/apidocs/#!/

 (see below if you want to try the API)


 Since we want to make it easy for web application to access our APIs, 
 we should use whatever technique works best for web applications. 
 Currently this means we must use REST over HTTP, HATEOAS, JSON 
 documents, JSON schemas and a focus on (good) (API) documentation.

 I do think the REST architecture style is better than most SOAP, CORBA 
 and ESB solutions and it currently is the best way to access remote 
 resources. But doing REST properly is not easy.

 The current API of MedRecord consists of two pieces:
 A fully automatically generated API based on the ADL files. 
 (everything starting with /ehr )
 And an API based on procedures (everything starting with /procedure )

 The main difference is that the procedure API can be used without any 
 knowledge of openEHR. All openEHR difficulties are hidden behind the 
 procedure API which should make the API simple enough to be usable by 
 any (UI) developer not familiar with openEHR or health care.

 These two APIs are different views on the openEHR data stored in a 
 database. This also means we can swap the backend which we are 
 currently using for any other openEHR backend.

 The MedRecord API also comes with Java (and JavaScript) client 
 libraries which hides all the REST stuff which makes accessing 
 resources as simple a single line of code while providing the data as 
 plain old Java objects.

 Also note we have two versions of MedRecord. A version based on XML 
 and a version not based on XML.
 Our current focus lies on the version without XML and this is the 
 version which can be seen in the link above.


 Since our API needs authentication, you can test our API if you go to 
 the following page:

 https://mr.dev.medvision360.org/mr/apidocs/#!/

 and use the text helloletmeinplease as authToken parameter.

 For example:

 https://mr.dev.medvision360.org/mr/ehr?authToken=helloletmeinplease

 lists all EHRs currently in our development server.


 Btw. this answer might be slightly off-topic but I wanted to explain 
 the process of how we developed our current API.


 Ralph.

 MedVision360

CRUD Restlet

2015-01-19 Thread Peter Gummer

Ralph van Etten wrote:

 This has lead to our current version of MedRecord (which is still work in 
 progress) and can be found here:
 
 https://mr.dev.medvision360.org/mr/apidocs/#!/


Hi Ralph,

That link doesn?t work. It displays this:

{error:406,message:The resource identified by the request is only capable 
of generating response entities which have content characteristics not 
acceptable according to the accept headers sent in the request,cause:user?}

- Peter

CRUD Restlet

2015-01-19 Thread Birger Haarbrandt

Works for me with the latests versions of chrome and firefox (windows)

Am 19.01.2015 13:44, schrieb Peter Gummer:
 Ralph van Etten wrote:

 This has lead to our current version of MedRecord (which is still work in 
 progress) and can be found here:

 https://mr.dev.medvision360.org/mr/apidocs/#!/

 Hi Ralph,

 That link doesn?t work. It displays this:

 {error:406,message:The resource identified by the request is only 
 capable of generating response entities which have content characteristics 
 not acceptable according to the accept headers sent in the 
 request,cause:user?}

 - Peter
 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org


-- 
*Birger Haarbrandt, M.Sc.*

Peter L. Reichertz Institut f?r Medizinische Informatik
Technische Universit?t Braunschweig und
Medizinische Hochschule Hannover
M?hlenpfordtstra?e 23
D-38106 Braunschweig

T +49 (0)531 391-2129
F +49 (0)531 391-9502
birger.haarbrandt at plri.de
http://www.plri.de

-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/27940f9d/attachment.html

CRUD Restlet

Hi Peter,

  This has lead to our current version of MedRecord (which is still 
work in progress) and can be found here:

 https://mr.dev.medvision360.org/mr/apidocs/#!/


 Hi Ralph,

 That link doesn?t work. It displays this:

 {error:406,message:The resource identified by the request is only 
 capable of generating response entities which have content characteristics 
 not acceptable according to the accept headers sent in the 
 request,cause:user?}

I am sorry to hear that.
Can you tell me what browser you are using and for which platform 
(Windows, OSX, Linux)?

Thanks,

Ralph van Etten
MedVision360


-- 
This e-mail message is intended exclusively for the addressee(s). Please 
inform us immediately if you are not the addressee.

CRUD Restlet

2015-01-19 Thread Peter Gummer

Hi Ralph,

Mac OS X 10.9.5 with Safari 7.1.2.

The first time I clicked on the link it asked me for a certificate, which 
seemed pointless to give it for API docs so I clicked Cancel. Then it displayed 
the error.

On subsequent attempts it goes straight to the error. I guess the browser must 
be remembering my initial response.

I had been hoping to see how a RESTful web service could be easy to use, since 
in my experience they?ve always been at least an order of magnitude more 
difficult than SOAP, at least with .NET systems where basically you just enter 
the URL and click a few buttons and hey presto, you have a bunch of proxy 
classes that you can easily program against with full type-safety ? as opposed 
to hours or days of reading docs, which are probably inaccurate, and 
trial-and-error tearing your hair out with frustration to find simple typos or 
type errors, wondering how you?ve suddenly time-travelled back into the 1970s. 
But maybe there are nice technologies out there for consuming RESTful services 
easily that I?ve never encountered, so I was intrigued to learn.

I do like your description of the API of MediRecord, even if am sceptical about 
its ease of use ;-)

Peter


On 20 Jan 2015, at 0:01, Ralph van Etten ralph at medvision360.com wrote:

 Hi Peter,
 
  This has lead to our current version of MedRecord (which is still work in 
  progress) and can be found here:
 
 https://mr.dev.medvision360.org/mr/apidocs/#!/
 
 
 Hi Ralph,
 
 That link doesn?t work. It displays this:
 
 {error:406,message:The resource identified by the request is only 
 capable of generating response entities which have content characteristics 
 not acceptable according to the accept headers sent in the 
 request,cause:user?}
 
 I am sorry to hear that.
 Can you tell me what browser you are using and for which platform (Windows, 
 OSX, Linux)?
 
 Thanks,
 
 Ralph van Etten
 MedVision360

CRUD Restlet

Hi,

On 01/19/2015 02:10 PM, Isabel Rom?n Mart?nez wrote:

 I do think the REST architecture style is better than most SOAP, CORBA
 and ESB solutions

 Sounds too categorical to me!! you must study case requirements deeply
 and you could not affirm this for every case!!

Sure, but I was talking about MedRecord and our current use cases. I was 
not trying to start a flame war about which architectural style is 
better. There are probably situations where ESB is a better solution but 
for MedRecord is isn't.


Ralph

MedVision360


-- 
This e-mail message is intended exclusively for the addressee(s). Please 
inform us immediately if you are not the addressee.

CRUD Restlet

2015-01-19 Thread Shinji KOBAYASHI

Hi Bert,

Thank you for proposing an interesting discussion whether http
response status should be included to API result or not.
I found this similar discussion on stackoverflow.
http://stackoverflow.com/questions/942951/rest-api-error-return-good-practices

I think using response 404 code is simple and easy to implement API.
But I partially agree with you that 404 error is not preferred because
we have to distinguish NO episode has been recorded and the record
shows no episode in his/her life in EHR as you mentioned.
IMO the former should be 404 response and the latter should be 200
response with null flavor message.

Shinji KOBAYASHI

2015-01-19 20:38 GMT+09:00 Bert Verhees bert.verhees at rosa.nl:
 On 19-01-15 11:31, Birger Haarbrandt wrote:

 The medrecord openEHR server is also based on REST and worth looking at.
 There was a lot to learn from for me as the API is pretty neat.


 I will check that too, thanks for the links

 Bert


 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

CRUD Restlet

Hi Peter,

 Mac OS X 10.9.5 with Safari 7.1.2.

Thanks, I'll look into it.


 The first time I clicked on the link it asked me for a certificate,
 which seemed pointless to give it for API docs so I clicked Cancel.
 Then it displayed the error.

Perhaps you can try the version without SSL?

http://mr.dev.medvision360.org/mr/apidocs/#!/



 I had been hoping to see how a RESTful web service could be easy to
 use, since in my experience they?ve always been at least an order of
 magnitude more difficult than SOAP, at least with .NET systems where
 basically you just enter the URL and click a few buttons and hey
 presto, you have a bunch of proxy classes that you can easily program
 against with full type-safety ? as opposed to hours or days of
 reading docs, which are probably inaccurate, and trial-and-error
 tearing your hair out with frustration to find simple typos or type
 errors, wondering how you?ve suddenly time-travelled back into the
 1970s. But maybe there are nice technologies out there for consuming
 RESTful services easily that I?ve never encountered, so I was
 intrigued to learn.

 I do like your description of the API of MediRecord, even if am
 sceptical about its ease of use ;-)

I agree with what you are saying and using a REST API directly in a 
application which is not a JavaScript application running in a web 
browser can be a challenge.

I absolutely feel the same about this and that's why we have a type safe 
Java (currently only Java but other languages are certainly possible) 
client library with those proxy classes you talk about.

We also have a PoC application which uses the JSON schemas to provide a 
similar 'type-safe' interface to JavaScript applications.

Also, all our documentation is generated from the same server source so 
it is always up to date and always matches reality.

Like I said, I share the same feelings about APIs as you do and I try my 
very best to make something which sucks less :)


Let me show some real Java examples of some of the integration tests we 
are using for MedRecord:


// basic configuration about where the server is and to set the
// authToken parameter so we can skip authentication on the test server
config = new ClientResourceConfig(https://mr.dev.medvision360.org/mr;);
config.addForcedQueryParameter(authToken, helloletmeinplease);


// create an EHR
// this calls POST /ehr
EhrSetResource ehrResource = new EhrSetResource(config);
Id ehr = ehrResource.createEhr();


// store an OQ-45 score in the EHR
// (the score object is just a POJO containing the
// answers to the questionnaire)
// this calls POST /procedure/oq45/{ehrId}
Oq45SetResource resource = new Oq45SetResource(
config,
ehr.getId()
);
IdWithLink id = resource.create(score);


// retrieve the score we just stored
// this calls GET /procedure/oq45/{ehrId}/{id}
Oq45Resource resource = new Oq45Resource(
config,
ehr.getId(),
id.getId()
);
Oq45Score score1 = resource.fetch();


All these calls communicate to MedRecord though the REST API using JSON 
documents.


The Javadocs for this client library can be found here:

https://javadoc.medvision360.org/model-client-jee/latest/latest/index.html?nl/medrecord/model/client/procedure/oq45/Oq45Resource.html

with the POJO containing the score answers here:

https://javadoc.medvision360.org/model-api-jee/latest/latest/index.html?nl/medrecord/model/model/ehr/observation/oq45/v1/Tree.html

This Tree object is automatically generated directly from the archetype 
and allows for a type safe way of accessing data.
This means the data is already validated on the client side even before 
it is send to the server. (It is using the Builder pattern for this)

For JavaScript (and other) clients we provide Json schemas which can be 
used to build and validate the data before sending it to the server.

http://mr.dev.medvision360.org/mr/schemas/objects/nl_medrecord_model_api_procedure_oq45_Oq45Score.json


BTW. for consuming REST APIs you should check out http://swagger.io/
It can generate those proxy classes for you. It is not what we are 
currently using because our solution predates swagger but I am 
considering upgrading :)


Ralph.

MedVision360


-- 
This e-mail message is intended exclusively for the addressee(s). Please 
inform us immediately if you are not the addressee.

CRUD Restlet

2015-01-19 Thread Thomas Beale

On 19/01/2015 10:29, Diego Bosc? wrote:
 I will just add that if you are making a server you probably want to
 take a look and how FHIR does things. They have some pretty cool ideas
 for common problems that you can probably reuse (e.g. using atom for
 query responses)


Diego,

I think they are ditching Atom I can't find it on the current 
release http://hl7.org/implement/standards/fhir/. I had a conversation 
with Grahame about this, but it's buried somewhere in a mass of FHIR 
posts and I can't locate it right now.

I'll ask about the status.

- thomas
-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150119/ecb075d4/attachment.html

CRUD Restlet

2015-01-19 Thread Thomas Beale


I would agree with Isabel.

Not everything is a resource, or should be seen as a resource. If you 
just want to pull back a lump of data, that could be a 'resource', and 
for that a REST service based on FHIR or some other API will make sense. 
Resource-oriented stateless services are suited to some kinds of 
applications, mostly readers in my view.

A service for talking directly to an EHR data store (i.e. a CDR) could 
be designed as a REST service in theory, but it's not that well matched 
to the kind of service interface of pattern of calls that will be made 
(especially if distributed queries and commits are to be supported).

The interesting question is: what style of service should be used for 
e-health business entities, like active care plans, managed medication 
lists, and order management, which all need much more complex APIs than 
just 'get'? FHIR is not designed for this kind of thing, and it's 
questionable whether REST is either. The APIs in these cases need to be 
carefully designed, and could easily be stateful / session-oriented - 
especially if they manage a shared resource that multiple agents may try 
to update simultaneously. In any case, I don't see statefulness or not 
as the decider on what kind of protocol you want; structure is a bigger 
decider.

I think it's easy to fall into the trap of thinking a single latest / 
fashionable protocol is good for all layers of a complex architecture. 
That's very unlikely to be true. I see no problem with an complete 
solution having REST, SOAP, binary RPC and other kinds of interfaces.

- thomas

On 19/01/2015 13:10, Isabel Rom?n Mart?nez wrote:
 Sorry, I know that this is not the list to have this discussion but 
 the sentence

 I do think the REST architecture style is better than most SOAP, 
 CORBA and ESB solutions

 Sounds too categorical to me!! you must study case requirements deeply 
 and you could not affirm this for every case!!

 States are crucial in many scenarios!! Supporting services (trading, 
 name, time, ...) are key in complex architectures!! Indirect 
 communication is essential in many healthcare scenarios!!
 REST could be the best for some situations but it is not the best in 
 any case!!

 I'm agree with the other part
 Doing REST properly is not easy. 
 As Doing any other thing in such complex use cases!!
 In fact doing REST properly is too much easy that doing CORBA, for 
 example, properly..., the easier use of REST architecture style 
 (versus other as SOA, Distributed objects, Agents...) is one of it 
 positive points!!

 Best Regards

 El 19/01/2015 a las 13:10, Ralph van Etten escribi?:
 Hi,


 On 01/19/2015 11:31 AM, Birger Haarbrandt wrote:

 The medrecord openEHR server is also based on REST and worth looking 
 at.
 There was a lot to learn from for me as the API is pretty neat.


 Thanks. We do our best to make the REST API of MedRecord as simple as 
 possible. We try to base the development of the API on actual 
 usecases and what kind of information in needed by (UI) clients 
 without requiring the users of our API to have any knowledge about 
 openEHR or know how things should work from a medical point of view.


 This has lead to our current version of MedRecord (which is still 
 work in progress) and can be found here:

 https://mr.dev.medvision360.org/mr/apidocs/#!/

 (see below if you want to try the API)


 Since we want to make it easy for web application to access our APIs, 
 we should use whatever technique works best for web applications. 
 Currently this means we must use REST over HTTP, HATEOAS, JSON 
 documents, JSON schemas and a focus on (good) (API) documentation.

 I do think the REST architecture style is better than most SOAP, 
 CORBA and ESB solutions and it currently is the best way to access 
 remote resources. But doing REST properly is not easy.

 The current API of MedRecord consists of two pieces:
 A fully automatically generated API based on the ADL files. 
 (everything starting with /ehr )
 And an API based on procedures (everything starting with /procedure )

 The main difference is that the procedure API can be used without any 
 knowledge of openEHR. All openEHR difficulties are hidden behind the 
 procedure API which should make the API simple enough to be usable by 
 any (UI) developer not familiar with openEHR or health care.

 These two APIs are different views on the openEHR data stored in a 
 database. This also means we can swap the backend which we are 
 currently using for any other openEHR backend.

 The MedRecord API also comes with Java (and JavaScript) client 
 libraries which hides all the REST stuff which makes accessing 
 resources as simple a single line of code while providing the data as 
 plain old Java objects.

 Also note we have two versions of MedRecord. A version based on XML 
 and a version not based on XML.
 Our current focus lies on the version without XML and this is the 
 version which can be seen in the link above.


 Since our API needs

CRUD Restlet

2015-01-19 Thread Diego Boscá

Sad to see that go away, I liked the idea of reusing well known formats for
everything.
Regarding REST, I assume that nothing stops you to provide a method called
query with the actual AQL query as a parameter :D

2015-01-19 21:58 GMT+01:00 Thomas Beale thomas.beale at oceaninformatics.com:


 I would agree with Isabel.

 Not everything is a resource, or should be seen as a resource. If you just
 want to pull back a lump of data, that could be a 'resource', and for that
 a REST service based on FHIR or some other API will make sense.
 Resource-oriented stateless services are suited to some kinds of
 applications, mostly readers in my view.

 A service for talking directly to an EHR data store (i.e. a CDR) could be
 designed as a REST service in theory, but it's not that well matched to the
 kind of service interface of pattern of calls that will be made (especially
 if distributed queries and commits are to be supported).

 The interesting question is: what style of service should be used for
 e-health business entities, like active care plans, managed medication
 lists, and order management, which all need much more complex APIs than
 just 'get'? FHIR is not designed for this kind of thing, and it's
 questionable whether REST is either. The APIs in these cases need to be
 carefully designed, and could easily be stateful / session-oriented -
 especially if they manage a shared resource that multiple agents may try to
 update simultaneously. In any case, I don't see statefulness or not as the
 decider on what kind of protocol you want; structure is a bigger decider.

 I think it's easy to fall into the trap of thinking a single latest /
 fashionable protocol is good for all layers of a complex architecture.
 That's very unlikely to be true. I see no problem with an complete solution
 having REST, SOAP, binary RPC and other kinds of interfaces.

 - thomas


 On 19/01/2015 13:10, Isabel Rom?n Mart?nez wrote:

 Sorry, I know that this is not the list to have this discussion but the
 sentence

 I do think the REST architecture style is better than most SOAP, CORBA
 and ESB solutions

 Sounds too categorical to me!! you must study case requirements deeply and
 you could not affirm this for every case!!

 States are crucial in many scenarios!! Supporting services (trading, name,
 time, ...) are key in complex architectures!! Indirect communication is
 essential in many healthcare scenarios!!
 REST could be the best for some situations but it is not the best in any
 case!!

 I'm agree with the other part
 Doing REST properly is not easy. 
 As Doing any other thing in such complex use cases!!
 In fact doing REST properly is too much easy that doing CORBA, for
 example, properly..., the easier use of REST architecture style (versus
 other as SOA, Distributed objects, Agents...) is one of it positive
 points!!

 Best Regards

 El 19/01/2015 a las 13:10, Ralph van Etten escribi?:

 Hi,


 On 01/19/2015 11:31 AM, Birger Haarbrandt wrote:

 The medrecord openEHR server is also based on REST and worth looking at.
 There was a lot to learn from for me as the API is pretty neat.



 Thanks. We do our best to make the REST API of MedRecord as simple as
 possible. We try to base the development of the API on actual usecases and
 what kind of information in needed by (UI) clients without requiring the
 users of our API to have any knowledge about openEHR or know how things
 should work from a medical point of view.


 This has lead to our current version of MedRecord (which is still work in
 progress) and can be found here:

 https://mr.dev.medvision360.org/mr/apidocs/#!/

 (see below if you want to try the API)


 Since we want to make it easy for web application to access our APIs, we
 should use whatever technique works best for web applications. Currently
 this means we must use REST over HTTP, HATEOAS, JSON documents, JSON
 schemas and a focus on (good) (API) documentation.

 I do think the REST architecture style is better than most SOAP, CORBA and
 ESB solutions and it currently is the best way to access remote resources.
 But doing REST properly is not easy.

 The current API of MedRecord consists of two pieces:
 A fully automatically generated API based on the ADL files. (everything
 starting with /ehr )
 And an API based on procedures (everything starting with /procedure )

 The main difference is that the procedure API can be used without any
 knowledge of openEHR. All openEHR difficulties are hidden behind the
 procedure API which should make the API simple enough to be usable by any
 (UI) developer not familiar with openEHR or health care.

 These two APIs are different views on the openEHR data stored in a
 database. This also means we can swap the backend which we are currently
 using for any other openEHR backend.

 The MedRecord API also comes with Java (and JavaScript) client libraries
 which hides all the REST stuff which makes accessing resources as simple a
 single line of code while providing the data

CRUD Restlet

2015-01-19 Thread Peter Gummer

Ralph van Etten wrote:

 Perhaps you can try the version without SSL?
 
 http://mr.dev.medvision360.org/mr/apidocs/#!/

Yes, Ralph, that version works for me.

Also, for the record, Ralph made the server less strict so that the original 
link that he gave us http://mr.dev.medvision360.org/mr/apidocs/#!/ also works 
for me now.


 I agree with what you are saying and using a REST API directly in a 
 application which is not a JavaScript application running in a web browser 
 can be a challenge.

Ah hah, that one sentence clarifies a lot! As so often is the case, it?s all 
about context.


 https://javadoc.medvision360.org/model-client-jee/latest/latest/index.html?nl/medrecord/model/client/procedure/oq45/Oq45Resource.html

I have the same SSL certificate problem here. It won?t let me in.


 BTW. for consuming REST APIs you should check out http://swagger.io/
 It can generate those proxy classes for you. It is not what we are currently 
 using because our solution predates swagger but I am considering upgrading :)

Now this looks interesting, especially the bit that says, almost every modern 
programming language and deployment environment.?

Peter

CRUD Restlet

2015-01-18 Thread Diego Boscá

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.
El 17/1/2015 23:35, Bert Verhees bert.verhees at rosa.nl escribi?:

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

On Sat, Jan 17, 2015 at 9:37 PM, Bert Verhees bert.verhees at rosa.nl
wrote:

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?

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

// 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 :-)

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. :-)

___
openEHR-technical mailing listopenEHR-technical at
lists.openehr.orghttp://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

___
openEHR-technical mailing list
openEHR-technical at lists.openehr.org

http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/72653a72/attachment.html

CRUD Restlet

2015-01-18 Thread pazospa...@hotmail.com

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 :)

Pablo.
Sent from my LG Mobile-- Original message--From: Bert VerheesDate: Sat,
Jan 17, 2015 8:35 PMTo: openehr-technical at lists.openehr.org;Subject:Re: CRUD
Restlet.

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 youreally need
to invent your own status code.
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 happensand
cannot proceed in its doing.

What should report to the user?

Error 404:? Or the party (partyId) you are looking for does notexist
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 understandthe
URL at all

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

Must be big fun.

Thank you (not) restlet for this

On Sat, Jan 17, 2015 at 9:37 PM, Bert
Verhees?bert.verhees at rosa.nl?wrote: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?
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

// 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 :-)?
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. :-)

___openEHR-technical mailing
listopenEHR-technical at
lists.openehr.orghttp://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/c29d1ffe/attachment-0001.html

CRUD Restlet

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.

Op zondag 18 januari 2015 heeft pazospablo at hotmail.com
pazospablo at hotmail.com het volgende geschreven:

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 :)

Pablo.

Sent from my LG Mobile

-- Original message--

*From: *Bert Verhees

*Date: *Sat, Jan 17, 2015 8:35 PM

*To: *openehr-technical at lists.openehr.org
javascript:_e(%7B%7D,'cvml','openehr-technical at lists.openehr.org');;

*Subject:*Re: CRUD Restlet
.

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?

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

On Sat, Jan 17, 2015 at 9:37 PM, Bert Verhees bert.verhees at rosa.nl
javascript:_e(%7B%7D,'cvml','bert.verhees at rosa.nl'); wrote:

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?

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

// Erik

P.s.

___openEHR-technical mailing
listopenEHR-technical at lists.openehr.org
javascript:_e(%7B%7D,'cvml','openEHR-technical at
lists.openehr.org');http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

CRUD Restlet


 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

CRUD Restlet

2015-01-18 Thread Erik Sundvall

Hi Bert!

Are you sure you have understood the difference between service orientation
and resource orientation? The background chapter in our paper I referred to
earlier briefly touches upon what a resource is, Fielding's dissertation
explains it in detail.

Why do you see the status 404 as an evil error status but 200 as some
totally other kind of status? Both are normal status codes telling
different things. If you consider 404 being an error or just a plain there
is no such resource/patient-id-message depends on context and your
perspective and what you expected to find at that uri. If you are sending
an invalid call to the resource/service you'll most likely get another
status code than 404. 404 often indicates that you sent a proper valid
request to a fully functional server server but asked for something that is
not there.

http://example.org/registry-x/id/123456 is a pointer to a specific
resource, either it exists or not. 404 says it does not. In the
implementation you describe it seems like patient IDs are modelled as
resources.

Most (good) REST designs will let you get information about usage and
status/availability of the containing resource (probably a or registry
id-query resource/service in your case) by chopping of the last piece of
the URL, for example http://example.org/registry-x/ or
http://example.org/registry-x/id/ if that is what you want to know the
status/availability of.

Best regards,
Erik Sundvall
Ph.D. Medical Informatics. Information Architect. Tel: +46-72-524 54 55 (or
010-1036252 in Sweden)
Region ?sterg?tland: erik.sundvall at regionostergotland.se (previously lio.se)
http://www.regionostergotland.se/cmit/
Link?ping University: erik.sundvall at liu.se, http://www.imt.liu.se/~erisu/

On Sun, Jan 18, 2015 at 11:21 AM, Bert Verhees bert.verhees at rosa.nl wrote:

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

___
openEHR-technical mailing list
openEHR-technical at lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-
technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/ef185396/attachment-0001.html

CRUD Restlet

On 18-01-15 11:32, Diego Bosc? wrote:

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.

I agree, using the HTTP-status is a tempting idea, because, it looks
like we are requesting a document. But we aren't. REST is not for a
normal document-service. For that a normal webserver is sufficient.
REST is for giving a web-interface to an application, and I ask that
application to create a document about a partyId, and that application
creates the document with information: This person is not in our system

That is not an error, the application gets a command to supply
information about a person in context of that application, and the
application does so.

I think that is good.

It sometimes happens that people are thinking in isolation. I know this
can happen to me. I am then making a point of something no-one seems to
make a point of.
But regardless that risk, I have posted this question to several forums
because I think this is important, and maybe I find support for my way
of thinking.

Bert

El 18/1/2015 11:21, Bert Verhees bert.verhees at rosa.nl
mailto:bert.verhees at rosa.nl escribi?:

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

___
openEHR-technical mailing list
openEHR-technical at lists.openehr.org
mailto:openEHR-technical at lists.openehr.org

http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

___
openEHR-technical mailing list
openEHR-technical at lists.openehr.org
http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/27033f94/attachment.html

CRUD Restlet

On 18-01-15 11:49, Erik Sundvall wrote:
 Why do you see the status 404 as an evil error status but 200 as some 
 totally other kind of status?
Restlet has implemented 404 as an evil error: it means: if it cannot 
route your URL, it returns 404.
So a client application has no useful information from that 404.

The client application has to take further steps to interpret the 404 
status. This is inefficient.

Bert

CRUD Restlet

For information:

See therecommendations by Ethan Cerami: Specialties: Cancer genomics,
bioinformatics, scientific computing, software engineering, project
management.
https://www.linkedin.com/in/ecerami
http://www.oreilly.com/pub/au/806

Read:
http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1

Quoting:

Conclusion:

* *Human Readable Error Messages:* Part of the major appeal of REST
based web services is that you can open any browser, type in the
right URL, and see an immediate response -- no special tools needed.
However, HTTP error codes do not always provide enough information.
For example, if we take option 1 above, and request and invalid book
ID, we get back a 404 Error Code. From the developer perspective,
have we actually typed in the wrong host name, or an invalid book
ID? It's not immediately clear. In Option 3 (DAS), we get back a
blank page with no information. To view the actual error code, you
need to run a network sniffer, or point your browser through a
proxy. For all these reasons, I think Option 4 has a lot to offer.
It significantly lowers the barrier for new developers, and enables
all information related to a web service to be directly viewable
within a web browser.
* *Application Specific Errors:* Option 1 has the disadvantage of not
being directly viewable within a browser. It also has the additional
disadvantage of mapping all HTTP error codes to application specific
error codes. HTTP status codes are specific to document retrieval
and posting, and these may not map directly to your application
domain. For example, one of the DAS error codes relates to invalid
genomic coordinates (sequence coordinate is out of bounds/invalid).
What HTTP error code would we map to in this case?
* *Machine Readable Error Codes:* As a third criteria, error codes
should be easily readable by other applications. For example, the
XooMLe application returns back only human readable error messages,
e.g. Invalid Google API key supplied. An application parsing a
XooMLe response would have to search for this specific error
message, and this can be notoriously brittle -- for example, the
XooMLe server might simply change the message to Invalid Key
Supplied. Error codes, such as those provided by DAS are important
for programmatic control, and easy creation of exceptions. For
example, if XooMLe returned a 1001 error code, a client application
could do a quick lookup and immediately throw an /InvalidKeyException./

Based on these three criteria, here's my vote for best error handling
option:

* Use HTTP Status Codes for problems specifically related to HTTP, and
not specifically related to your web service.
* When an error occurs, always return an XML document detailing the
error.
* Make sure the XML error document contains both an error code, and a
human readable error message. For example:
?xml version=1.0 encoding=UTF-8 ?
error
error_code1001/error_code
error_msgInvalid Google API key supplied/error_msg
/error

By following these three simple practices, you can make it significantly
easier for others to interface with your service, and react when things
go wrong. New developers can easily see valid and invalid requests via a
simple web browser, and programs can easily (and more robustly) extract
error codes and act appropriately.

The Amazon.com web services API follows the approach of returned XML
document can specify an /ErrorMsg/ element.
XooMLe also follows this approach. (XooMLe provides a RESTful API
wrapper to the existing SOAP based Google API).
Another approach is by DAS ( Distributed Annotation System) which always
returns 200 if there was no HTTP-error and has error information in the
HTTP-header, which is less favorable, because it is not human readable,
as a browser does not display the HTTP-header.

---
End Quoting

Best regards
Bert

-- next part --
An HTML attachment was scrubbed...
URL:
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/c46a8d6f/attachment.html

CRUD Restlet

2015-01-18 Thread pazospa...@hotmail.com







NP, but it is not a matter of opinion when there are conventions, 
principles and guidelines. Of course it is your decision to not follow.
BTW, I've found that the Facebook API returns 200 even if there are app level 
errors.
So I think this is a by-API decision. If you want to implement a client for an 
API, you should follow the rules defined by that API.
Cheers,Pablo.



-- Original message--From: Bert VerheesDate: Sun, Jan 18, 2015 6:22 
AMTo: pazospablo at hotmail.com;Cc: openehr-technical at 
lists.openehr.org;Subject:Re: CRUD Restletthanks,?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 regardsBert.

Op zondag 18 januari 2015 heeft pazospablo at hotmail.com pazospablo at 
hotmail.com het volgende geschreven:
  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 :)


-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/285d266a/attachment.html

CRUD Restlet

2015-01-18 Thread pazospa...@hotmail.com





  

The recommendations seem a little weak for me.
1. Most REST services can not be accessed just by typing the url in the 
browser. What about security tokens? Or header values? Or sending PUT, POST, 
PATCH or DELETE?
2. No serious developer will use just the browser and not any other tools. This 
is plain dumb. We use a bunch of tools for dev and test, from packet sniffers 
and REST testers, to javascript consoles and log analyzers.
3. REST services should be documented, so the developer knows for sure what 404 
means in each case and has the correct urls for every resource :)

Sent from my LG Mobile


-- Original message--From: Bert VerheesDate: Sun, Jan 18, 2015 9:46 
AMTo: openehr-technical at lists.openehr.org;Subject:Re: CRUD RestletFor 
information:

See the recommendations by Ethan Cerami:Specialties: Cancer genomics, 
bioinformatics, scientific computing,software engineering, project 
management.
https://www.linkedin.com/in/ecerami
http://www.oreilly.com/pub/au/806

Read:
http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1

Quoting: 

Conclusion:
  Human Readable Error Messages: Part of the major appealof 
REST based web services is that you can open any browser,type in the 
right URL, and see an immediate response -- nospecial tools needed. 
However, HTTP error codes do not alwaysprovide enough information. For 
example, if we take option 1above, and request and invalid book ID, we 
get back a 404 ErrorCode. From the developer perspective, have we 
actually typed inthe wrong host name, or an invalid book ID? It's not 
immediatelyclear. In Option 3 (DAS), we get back a blank page with no   
 information. To view the actual error code, you need to run a
network sniffer, or point your browser through a proxy. For allthese 
reasons, I think Option 4 has a lot to offer. Itsignificantly lowers 
the barrier for new developers, and enablesall information related to a 
web service to be directly viewablewithin a web browser.  
Application Specific Errors: Option 1 has thedisadvantage of not being 
directly viewable within a browser. Italso has the additional 
disadvantage of mapping all HTTP errorcodes to application specific 
error codes. HTTP status codes arespecific to document retrieval and 
posting, and these may notmap directly to your application domain. For 
example, one of theDAS error codes relates to invalid genomic 
coordinates (sequencecoordinate is out of bounds/invalid). What HTTP 
error code wouldwe map to in this case?Machine Readable 
Error Codes: As a third criteria,error codes should be easily readable 
by other applications. Forexample, the XooMLe application returns back 
only human readableerror messages, e.g. Invalid Google API key 
supplied. Anapplication parsing a XooMLe response would have to search 
forthis specific error message, and this can be notoriously brittle 
   -- for example, the XooMLe server might simply change themessage to 
Invalid Key Supplied. Error codes, such as thoseprovided by DAS are 
important for programmatic control, and easycreation of exceptions. For 
example, if XooMLe returned a 1001error code, a client application 
could do a quick lookup andimmediately throw an InvalidKeyException.
Based on these three criteria, here's my vote for best error  handling 
option:
  
  Use HTTP Status Codes for problems specifically related toHTTP, 
and not specifically related to your web service.
When an error occurs, always return an XML document detailing   
 the error. 
Make sure the XML error document contains both an error code,   
 and a human readable error message. For example:
 
error
1001 
error_msgInvalid Google API keysupplied/error_msg 
/errorBy following these three simple practices, you can make 
it  significantly easier for others to interface with your service,  
and react when things go wrong. New developers can easily see  valid and 
invalid requests via a simple web browser, and programs  can easily (and 
more robustly) extract error codes and act  appropriately.The 
Amazon.com web services API follows the approach of returned XMLdocument 
can specify an ErrorMsg element.
XooMLe also follows this approach. (XooMLe provides a RESTful API
wrapper to the existing SOAP based Google API).
Another approach is by DAS ( Distributed Annotation System) whichalways 
returns 200 if there was no HTTP-error and has errorinformation in the 
HTTP-header, which is less favorable, because itis not human readable

CRUD Restlet

The point for me is separation of transport layer and application layer, 
and each domain has its own errorhandling.

I have made my choice. And it seems I am not the only one on the world 
with this choice, which is good news

thanks
Bert


pazospablo at hotmail.com schreef op 18-1-2015 om 19:52:

 The recommendations seem a little weak for me.


 1. Most REST services can not be accessed just by typing the url in 
 the browser. What about security tokens? Or header values? Or sending 
 PUT, POST, PATCH or DELETE?


 2. No serious developer will use just the browser and not any other 
 tools. This is plain dumb. We use a bunch of tools for dev and test, 
 from packet sniffers and REST testers, to javascript consoles and log 
 analyzers.


 3. REST services should be documented, so the developer knows for sure 
 what 404 means in each case and has the correct urls for every resource :)



 Sent from my LG Mobile

 -- Original message--

 *From: *Bert Verhees

 *Date: *Sun, Jan 18, 2015 9:46 AM

 *To: *openehr-technical at lists.openehr.org 
 mailto:openehr-technical at lists.openehr.org;

 *Subject:*Re: CRUD Restlet

 For information:

 See therecommendations by Ethan Cerami: Specialties: Cancer genomics, 
 bioinformatics, scientific computing, software engineering, project 
 management.
 https://www.linkedin.com/in/ecerami
 http://www.oreilly.com/pub/au/806

 Read:
 http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1

 Quoting:

 Conclusion:

   * *Human Readable Error Messages:* Part of the major appeal of REST
 based web services is that you can open any browser, type in the
 right URL, and see an immediate response -- no special tools
 needed. However, HTTP error codes do not always provide enough
 information. For example, if we take option 1 above, and request
 and invalid book ID, we get back a 404 Error Code. From the
 developer perspective, have we actually typed in the wrong host
 name, or an invalid book ID? It's not immediately clear. In Option
 3 (DAS), we get back a blank page with no information. To view the
 actual error code, you need to run a network sniffer, or point
 your browser through a proxy. For all these reasons, I think
 Option 4 has a lot to offer. It significantly lowers the barrier
 for new developers, and enables all information related to a web
 service to be directly viewable within a web browser.
   * *Application Specific Errors:* Option 1 has the disadvantage of
 not being directly viewable within a browser. It also has the
 additional disadvantage of mapping all HTTP error codes to
 application specific error codes. HTTP status codes are specific
 to document retrieval and posting, and these may not map directly
 to your application domain. For example, one of the DAS error
 codes relates to invalid genomic coordinates (sequence coordinate
 is out of bounds/invalid). What HTTP error code would we map to in
 this case?
   * *Machine Readable Error Codes:* As a third criteria, error codes
 should be easily readable by other applications. For example, the
 XooMLe application returns back only human readable error
 messages, e.g. Invalid Google API key supplied. An application
 parsing a XooMLe response would have to search for this specific
 error message, and this can be notoriously brittle -- for example,
 the XooMLe server might simply change the message to Invalid Key
 Supplied. Error codes, such as those provided by DAS are
 important for programmatic control, and easy creation of
 exceptions. For example, if XooMLe returned a 1001 error code, a
 client application could do a quick lookup and immediately throw
 an /InvalidKeyException./

 Based on these three criteria, here's my vote for best error handling 
 option:


   * Use HTTP Status Codes for problems specifically related to HTTP,
 and not specifically related to your web service.
   * When an error occurs, always return an XML document detailing the
 error.
   * Make sure the XML error document contains both an error code, and
 a human readable error message. For example:

 error
 1001
 error_msgInvalid Google API key supplied/error_msg
 /error

 By following these three simple practices, you can make it 
 significantly easier for others to interface with your service, and 
 react when things go wrong. New developers can easily see valid and 
 invalid requests via a simple web browser, and programs can easily 
 (and more robustly) extract error codes and act appropriately.

 The Amazon.com http://Amazon.com web services API follows the 
 approach of returned XML document can specify an /ErrorMsg/ element.
 XooMLe also follows this approach. (XooMLe provides a RESTful API 
 wrapper to the existing SOAP based Google API).
 Another approach is by DAS ( Distributed Annotation System) which 
 always returns 200

CRUD Restlet

2015-01-18 Thread pablo pazos

But the recommendations you posted are built over false arguments, like the #1. 
in my list on the previous message.
Also, the date of the post you reference is from ~ 2003 ...

IMO the bad news is you will not be able to use a lot of APIs that follow 
principles and conventions you don't like, like the EHRScape ;)

-- 
Kind regards,
Eng. Pablo Pazos Guti?rrez
http://cabolabs.com

Date: Sun, 18 Jan 2015 20:41:35 +0100
From: bert.verh...@rosa.nl
To: pazospablo at hotmail.com; openehr-technical at lists.openehr.org
Subject: Re: CRUD Restlet


  

  
  
The point for me is separation of
  transport layer and application layer, and each domain has its own
  errorhandling.

  

  I have made my choice. And it seems I am not the only one on the
  world with this choice, which is good news

  

  thanks

  Bert

  

  

  pazospablo at hotmail.com schreef op 18-1-2015 om 19:52:



  
  
The
  recommendations seem a little weak for me.



1. Most REST
  services can not be accessed just by typing the url in the
  browser. What about security tokens? Or header values? Or
  sending PUT, POST, PATCH or DELETE?



2. No
  serious developer will use just the browser and not any other
  tools. This is plain dumb. We use a bunch of tools for dev and
  test, from packet sniffers and REST testers, to javascript
  consoles and log analyzers.



3. REST
  services should be documented, so the developer knows for sure
  what 404 means in each case and has the correct urls for every
  resource :)






Sent from my LG Mobile
  
  
--
  Original message--
From: Bert
  Verhees
Date: Sun,
  Jan 18, 2015 9:46 AM
To: openehr-technical at lists.openehr.org;
Subject:Re:
  CRUD Restlet
For information:



See the recommendations by Ethan Cerami:
Specialties: Cancer genomics, bioinformatics, scientific
computing, software engineering, project management.

https://www.linkedin.com/in/ecerami

http://www.oreilly.com/pub/au/806



Read:


http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1



Quoting: 



Conclusion:


  Human Readable Error Messages: Part of the major
appeal of REST based web services is that you can open any
browser, type in the right URL, and see an immediate
response -- no special tools needed. However, HTTP error
codes do not always provide enough information. For example,
if we take option 1 above, and request and invalid book ID,
we get back a 404 Error Code. From the developer
perspective, have we actually typed in the wrong host name,
or an invalid book ID? It's not immediately clear. In Option
3 (DAS), we get back a blank page with no information. To
view the actual error code, you need to run a network
sniffer, or point your browser through a proxy. For all
these reasons, I think Option 4 has a lot to offer. It
significantly lowers the barrier for new developers, and
enables all information related to a web service to be
directly viewable within a web browser.
  Application Specific Errors: Option 1 has the
disadvantage of not being directly viewable within a
browser. It also has the additional disadvantage of mapping
all HTTP error codes to application specific error codes.
HTTP status codes are specific to document retrieval and
posting, and these may not map directly to your application
domain. For example, one of the DAS error codes relates to
invalid genomic coordinates (sequence coordinate is out of
bounds/invalid). What HTTP error code would we map to in
this case? 
  Machine Readable Error Codes: As a third criteria,
error codes should be easily readable by other applications.
For example, the XooMLe application returns back only human
readable error messages, e.g. Invalid Google API key
supplied. An application parsing a XooMLe response would
have to search for this specific error message, and this can
be notoriously brittle -- for example, the XooMLe server
might simply change the message to Invalid Key Supplied.
Error codes, such as those provided by DAS are important for
programmatic control, and easy creation of exceptions. For
example, if XooMLe returned a 1001 error code

CRUD Restlet

 Also, the date of the post you reference is from ~ 2003

The Rest protocol is very old, maybe 15 years, and hasn't changed much, so
are some recommandations. I don't know from which date the recommandation
is to use HTTP- status for application error handling. I don't think that
should be an argument.

And I am not writing client software, so I do not have to follow Api's from
others. I am offering API's. I think a client is best served with an own
defined error-handling instead of using the error-handling of another layer
which is designed for other reasons. This argument was also in that
document.

I was just not sure if my choice was a good one, that was, for me, the
reason for the discussion.
But also on private level I got recommandations to follow my own idea, and
I also found some supporting links.

An application can have own error-handling needs. There was an example in
that document. Similar examples I have too, where the mapping to the HTTP
number schema feels unnatural, or by far too rudimentory. Being
contra-intuitive in application API's is something to avoid, in my opinion.

For example, saying that a resource is not available is a poor API's
choice. Applications can be in need for a much more complex schema of
errors, and it is good if an hierarchical system is possible.

Why is a requested resource not available? Is it locked by the database?
Has it ever been available, is it tomorrow available, has it brought to an
archive system which needs an other Url or method, has the call been routed
to another service or server, and is there something the matter? Just
examples.

I was looking at the PayPal API about authentication, they had defined over
hundred things that can go wrong in an authentication-process. This needs a
fine grained and extensible error-handling.

Another reason is that, for example, the 404 will also be thrown for
HTTP-technical reasons, inside Restlet, it is used for other reasons. It
is confusing for a client with a 404 for application-reasons which need a
entirely other action to be resolved. This was, I thought, also an argument
from the link I posted.

Anyway, I made my choice, and with support from some important people in my
activity-context, so I follow that way.

But thanks again for your arguments, they gave me something to think about.

Bert.

Op zondag 18 januari 2015 heeft pablo pazos pazospablo at hotmail.com
javascript:_e(%7B%7D,'cvml','pazospablo at hotmail.com'); het volgende
geschreven:

 But the recommendations you posted are built over false arguments, like
 the #1. in my list on the previous message.

 Also, the date of the post you reference is from ~ 2003 ...

 IMO the bad news is you will not be able to use a lot of APIs that follow
 principles and conventions you don't like, like the EHRScape ;)

 --
 Kind regards,
 Eng. Pablo Pazos Guti?rrez
 http://cabolabs.com http://cabolabs.com/es/home
 http://twitter.com/ppazos

 Subject: Re: CRUD Restlet

 The point for me is separation of transport layer and application layer,
 and each domain has its own errorhandling.

 I have made my choice. And it seems I am not the only one on the world
 with this choice, which is good news

 thanks
 Bert


 pazospablo at hotmail.com schreef op 18-1-2015 om 19:52:




  The recommendations seem a little weak for me.


  1. Most REST services can not be accessed just by typing the url in the
 browser. What about security tokens? Or header values? Or sending PUT,
 POST, PATCH or DELETE?


  2. No serious developer will use just the browser and not any other
 tools. This is plain dumb. We use a bunch of tools for dev and test, from
 packet sniffers and REST testers, to javascript consoles and log analyzers.


  3. REST services should be documented, so the developer knows for sure
 what 404 means in each case and has the correct urls for every resource :)



  Sent from my LG Mobile

 -- Original message--

 *From: *Bert Verhees

 *Date: *Sun, Jan 18, 2015 9:46 AM

 *To: *openehr-technical at lists.openehr.org;

 *Subject:*Re: CRUD Restlet
 For information:

 See the recommendations by Ethan Cerami: Specialties: Cancer genomics,
 bioinformatics, scientific computing, software engineering, project
 management.
 https://www.linkedin.com/in/ecerami
 http://www.oreilly.com/pub/au/806

 Read:

 http://archive.oreilly.com/pub/post/restful_error_handling.html#__federated=1

 Quoting:

 Conclusion:

- *Human Readable Error Messages:* Part of the major appeal of REST
based web services is that you can open any browser, type in the right URL,
and see an immediate response -- no special tools needed. However, HTTP
error codes do not always provide enough information. For example, if we
take option 1 above, and request and invalid book ID, we get back a 404
Error Code. From the developer perspective, have we actually typed in the
wrong host name, or an invalid book ID? It's not immediately clear. In
Option 3 (DAS), we get back a blank page

CRUD Restlet

2015-01-18 Thread Peter Gummer

Bert Verhees wrote:

The point for me is separation of transport layer and application layer, and 
each domain has its own errorhandling.


Hi Bert,

HTTP is not a transport layer protocol:

http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

?The Hypertext Transfer Protocol (HTTP) is an application 
protocolhttp://en.wikipedia.org/wiki/Application_protocol ?

Thanks for the discussion, though. I?ve learned a lot from it.

Peter
-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150118/d409ec94/attachment.html

CRUD Restlet

2015-01-17 Thread Diego Boscá

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).
El 17/1/2015 2:19, pazospablo at hotmail.com pazospablo at hotmail.com
escribi?:

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


 Sent from my LG Mobile

 -- Original message--

 *From: *Bert Verhees

 *Date: *Fri, Jan 16, 2015 8:18 PM

 *To: *For openEHR technical discussions;

 *Subject:*CRUD Restlet
 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

 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org

 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150117/7a890941/attachment.html

CRUD Restlet

On 17-01-15 10:24, Diego Bosc? wrote:

 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).


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

 El 17/1/2015 2:19, pazospablo at hotmail.com 
 mailto:pazospablo at hotmail.com pazospablo at hotmail.com 
 mailto:pazospablo at hotmail.com escribi?:

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


 Sent from my LG Mobile

 -- Original message--

 *From: *Bert Verhees

 *Date: *Fri, Jan 16, 2015 8:18 PM

 *To: *For openEHR technical discussions;

 *Subject:*CRUD Restlet

 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

 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 mailto:openEHR-technical at lists.openehr.org
 
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org


-- next part --
An HTML attachment was scrubbed...
URL: 
http://lists.openehr.org/pipermail/openehr-technical_lists.openehr.org/attachments/20150117/6b659678/attachment-0001.html

CRUD Restlet

2015-01-17 Thread Karsten Hilbert

On Sat, Jan 17, 2015 at 11:37:52AM +0100, Diego Bosc? wrote:

 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
-- 
GPG key ID E4071346 @ eu.pool.sks-keyservers.net
E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346

CRUD Restlet

2015-01-17 Thread Diego Boscá

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

2015-01-17 11:56 GMT+01:00 Karsten Hilbert Karsten.Hilbert at gmx.net:
 On Sat, Jan 17, 2015 at 11:37:52AM +0100, Diego Bosc? wrote:

 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
 --
 GPG key ID E4071346 @ eu.pool.sks-keyservers.net
 E167 67FD A291 2BEA 73BD  4537 78B9 A9F9 E407 1346

 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

CRUD Restlet

On 17-01-15 12:00, Diego Bosc? wrote:
 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

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

CRUD Restlet

On 17-01-15 11:56, Karsten Hilbert wrote:
 What would be the error code for when the client attempts to
 call a non-existing service on the server ?

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

CRUD Restlet

2015-01-17 Thread Sebastian Iancu

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

On 1/17/2015 6:20 PM, Bert Verhees wrote:
 On 17-01-15 11:56, Karsten Hilbert wrote:
 What would be the error code for when the client attempts to
 call a non-existing service on the server ?

 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

 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org

CRUD Restlet

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
Date:Sat, 17 Jan 2015 22:19:42 GMT






On 17-01-15 21:27, Sebastian Iancu wrote:
 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

 On 1/17/2015 6:20 PM, Bert Verhees wrote:
 On 17-01-15 11:56, Karsten Hilbert wrote:
 What would be the error code for when the client attempts to
 call a non-existing service on the server ?

 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

 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org
 http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org
  



 ___
 openEHR-technical mailing list
 openEHR-technical at lists.openehr.org

CRUD Restlet