I maintain a library that provides XML/A access trhough javascript: https://github.com/rpbouman/xmla4js
Mostly it works ok, but I would like to improve handling of error responses. As far as I understand the XML/A spec corectly, error responses take this form:
<SOAP-ENV:Envelope>
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>...</faultcode>
<faultstring>...</faultstring>
<faultactor>...</faultactor>
<detail>
...
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
However, I found that at least for Mondrian (the XML/A provider I am most familiar with) the <detail> element often contains invaluable information. For instance, the general <faultcode> element may say something generic like "datasource not found" whereas the <detail> element may contain something like:
<XA:error xmlns:XA="http://mondrian.sourceforge.net">
<code>00HSBC01</code>
<desc>The Mondrian XML: MondrianOneToOneUserRoleListMapper.ERROR_001_ - Access is denied because the roles of this user don't correspond to any present in the Mondrian schema requested.</desc>
</XA:error>
Which indicates a rather more specific condition.
My question is, is there some kind of pattern in the error response of other XML/A providers that I can use to impove my api and provide better error messages to the users of my library? If you don't know about a patter but can only provide samples of XML/A providers you happen to have access to than that is also greatly appreciated. Thank you!
You can download the Microsoft specification of the XMLA protocol here: http://msdn.microsoft.com/en-us/library/ee320606.aspx (more than seven hundred pages).
In general, there are two types of errors:
Global ones, that either prevent the request from being executed, or prevent the server from returning anything useful (e. g. syntax errors),
and local ones, e. g. within a single cell of a response to an MDX SELECT request where the general result structure is returned. In this case error objects may be returned e. g. in one or several cells instead of the result. An example would be an error an prevents the server from calculating this specific cell value, like a reference to an unknown element in the definition of a calculated member.
Related
All, Forgive me I am a newbie in the DICOM world. I tried to learn the DCMTk tools to talk with PACS server. But didn't found much tutorial or sample in the internet to know enough about it .Currently I just have the offical document to read.
I just tried the findscu.exe to test c-find command .
I remembered C-Find would return what specified in the request message. for example. If I only specifed the condition Patient Name ='abc' then the reponse would return only attribute Patient Name. Nothing else.( If it is not right . Please correct me.)
So I want to know how to return all the attribute of response DICOM.
Thanks.
How to specified multiple attributes in the findscu command.
Just specify multiple --key (-k) options on the command line. Alternatively, you could also use a "query file" as described in the man page.
So I want to know how to return all the attribute of response DICOM.
Then, you have to specify all attributes (keys) you are interested in. That's how C-FIND works.
By the way, if you are querying a PACS (Query/Retrieve SCP), then you also have to specify the Query/Retrieve Level (0008,0052), e.g. "PATIENT".
Currently I just have the offical document to read.
If you think that the examples in the man page of the findscu tool are not sufficient (and you are actually querying a PACS), this HOWTO might be useful too.
It is totally legal to send a request with Patient Name information only and the PACS will return all matching datasets.
Each dataset should at least contain all mandatory fields like Date of Birth, Patient ID, and so on, depending on the Query Level.
What information is returned by the PACS system on each Query Level should be specified in the DICOM Conformance Statement of the vendor. I would recommend to take a look at this to know, how to set up a valid query to get the information you need and/or if the information is provided by the PACS system.
It is best to include the Unique key and Required Key Attributes in the request attribute list. Also, include the optional attributes (if supported by SCP) when you wish server to return values for them. Please refer to DICOM Standard PS 3.4 section C.2 and C.3 detail information on Query/Retrieve service. List of attribute and type (Unique, Required, Optional) is listed section C.6.1.1.2 (Patient Level), C.6.1.1.3 (Study Level) and so on.
Let's say I have a component wich performs an addition as a business operation.
I don't need the result of the sum to be persisted anywhere because, let's say, the only thing that matters is the result of the addition.
Let´s say that the client component should get interested in saving the result of the addition, so I need to indicate the client how to save the result of the addition, so he can come back later and retrieve this result.
May the addition service be modeled as a web resource? Something like:
GET api.mycompany.com/addition?param1=x¶m2=y
should return the result of the business operation. The response may present the following as a link (here comes the hypermedia) to persist the result:
POST api.mycompany.com/addition?param1=x¶m2=y
Is this approach correct? -In the sense of a truly restful api -
Considering CRUD operations, this one:
GET api.mycompany.com/addition?param1=x¶m2=y
Is idempotent, safe and cacheable, so I'll consider it as a RESTful GET.
As soon as your parameters become more complex, you could POST them to your 'addition' resource, returning a URL to computed result.
Yes, it is fine. But perhaps it is better to have a resource called operation that returns a list of links to supported operations. You could then have operation/addition?param1=x¶m2=y and so on and so fort. Of course, the links should be opaque and the documented media-type returned by a call to the operation resource should provide information about the other available resources.
While the HTTP 1.1 spec seems to allow message bodies on DELETE requests, it seems to indicate that servers should ignore it since there are no defined semantics for it.
4.3 Message Body
A server SHOULD read and forward a message-body on any request; if the
request method does not include defined semantics for an entity-body,
then the message-body SHOULD be ignored when handling the request.
I've already reviewed several related discussions on this topic on SO and beyond, such as:
Is an entity body allowed for an HTTP DELETE request?
Payloads of HTTP Request Methods
HTTP GET with request body
Most discussions seem to concur that providing a message body on a DELETE may be allowed, but is generally not recommended.
Further, I've noticed a trend in various HTTP client libraries where more and more enhancements seem to be getting logged for these libraries to support request bodies on DELETE. Most libraries seem to oblige, although occasionally with a little bit of initial resistance.
My use case calls for the addition of some required metadata on a DELETE (e.g. the "reason" for deletion, along with some other metadata required for deletion). I've considered the following options, none of which seem completely appropriate and inline with HTTP specs and/or REST best practices:
Message Body - The spec indicates that message bodies on DELETE have no semantic value; not fully supported by HTTP clients; not standard practice
Custom HTTP Headers - Requiring custom headers is generally against standard practices; using them is inconsistent with the rest of my API, none of which require custom headers; further, no good HTTP response available to indicate bad custom header values (probably a separate question altogether)
Standard HTTP Headers - No standard headers are appropriate
Query Parameters - Adding query params actually changes the Request-URI being deleted; against standard practices
POST Method - (e.g. POST /resourceToDelete { deletemetadata }) POST is not a semantic option for deleting; POST actually represents the opposite action desired (i.e. POST creates resource subordinates; but I need to delete the resource)
Multiple Methods - Splitting the DELETE request into two operations (e.g. PUT delete metadata, then DELETE) splits an atomic operation into two, potentially leaving an inconsistent state. The delete reason (and other related metadata) are not part of the resource representation itself.
My first preference would probably be to use the message body, second to custom HTTP headers; however, as indicated, there are some downsides to these approaches.
Are there any recommendations or best practices inline with REST/HTTP standards for including such required metadata on DELETE requests? Are there any other alternatives that I haven't considered?
Despite some recommendations not to use the message body for DELETE requests, this approach may be appropriate in certain use cases. This is the approach we ended up using after evaluating the other options mentioned in the question/answers, and after collaborating with consumers of the service.
While the use of the message body is not ideal, none of the other options were perfectly fitting either. The request body DELETE allowed us to easily and clearly add semantics around additional data/metadata that was needed to accompany the DELETE operation.
I'd still be open to other thoughts and discussions, but wanted to close the loop on this question. I appreciate everyone's thoughts and discussions on this topic!
Given the situation you have, I would take one of the following approaches:
Send a PUT or PATCH: I am deducing that the delete operation is virtual, by the nature of needing a delete reason. Therefore, I believe updating the record via a PUT/PATCH operation is a valid approach, even though it is not a DELETE operation per se.
Use the query parameters: The resource uri is not being changed. I actually think this is also a valid approach. The question you linked was talking about not allowing the delete if the query parameter was missing. In your case, I would just have a default reason if the reason is not specified in the query string. The resource will still be resource/:id. You can make it discoverable with Link headers on the resource for each reason (with a rel tag on each to identify the reason).
Use a separate endpoint per reason: Using a url like resource/:id/canceled. This does actually change the Request-URI and is definitely not RESTful. Again, link headers can make this discoverable.
Remember that REST is not law or dogma. Think of it more as guidance. So, when it makes sense to not follow the guidance for your problem domain, don't. Just make sure your API consumers are informed of the variance.
What you seem to want is one of two things, neither of which are a pure DELETE:
You have two operations, a PUT of the delete reason followed by a DELETE of the resource. Once deleted, the contents of the resource are no longer accessible to anyone. The 'reason' cannot contain a hyperlink to the deleted resource. Or,
You are trying to alter a resource from state=active to state=deleted by using the DELETE method. Resources with state=deleted are ignored by your main API but might still be readable to an admin or someone with database access. This is permitted - DELETE doesn't have to erase the backing data for a resource, only to remove the resource exposed at that URI.
Any operation which requires a message body on a DELETE request can be broken down into at it's most general, a POST to do all the necessary tasks with the message body, and a DELETE. I see no reason to break the semantics of HTTP.
I suggest you include the required metadata as part of the URI hierarchy itself. An example (Naive):
If you need to delete entries based on a date range, instead of passing the start date and end date in body or as query parameters, structure the URI such a way that you pass the required information as part of the URI.
e.g.
DELETE /entries/range/01012012/31122012 -- Delete all entries between 01 January 2012 to 31st December 2012
Hope this helps.
I would say that query parameters are part of the resource definition, thus you can use them to define the scope of your operation, then "apply" the operation.
My conclusion is that Query Parameters as you defined it is the best approach.
When i have a resource, let's say customers/3 which returns the customer object and i want to return this object with different fields, or some other changes (for example let's say i need to have include in customer object also his latest purchase (for the sake of speed i dont want to do 2 different queries)).
As i see it my options are:
customers/3/with-latest-purchase
customers/3?display=with-latest-purchase
In the first option there is distinct URI for the new representation, but is this REALLY needed? Also how do i tell the client that this URI exist?
In the second option there is GET parameter telling the server what kind of representation to return. The URI parameters can be explained through OPTIONS method and it is easier to tell client where to look for the data as all the representations are all in one place.
So my question is which of these is better (more RESTful) and/or is there some better way to do this that i do not know about?
I think what is best is to define atomic, indivisible service objects, e.g. customer and customer-latest-purchase, nice, clean, simple. Then if the client wants a customer with his latest purchases, they invoke both service calls, instead of jamming it all in one with funky parameters.
Different representations of an object is OK in Java through interfaces but I think it is a bad idea for REST because it compromises its simplicity.
There is a misconception that making query parameters look like file paths is more RESTful. The query portion of the address is included when determining a distinct URI so the second option is fine.
Is there much of a performance hit in including the latest purchase data in all customer GET requests? If not, the simplest thing would be to do that so there would neither be weird URL params or double requests. If getting the latest order is a significant hardship (which it probably shouldn't be) there is nothing wrong with adding a flag in the query string to include it.
I have a resource that has a counter. For the sake of example, let's call the resource profile, and the counter is the number of views for that profile.
Per the REST wiki, PUT requests should be used for resource creation or modification, and should be idempotent. That combination is fine if I'm updating, say, the profile's name, because I can issue a PUT request which sets the name to something 1000 times and the result does not change.
For these standard PUT requests, I have browsers do something like:
PUT /profiles/123?property=value&property2=value2
For incrementing a counter, one calls the url like so:
PUT /profiles/123/?counter=views
Each call will result in the counter being incremented. Technically it's an update operation but it violates idempotency.
I'm looking for guidance/best practice. Are you just doing this as a POST?
I think the right answer is to use PATCH. I didn't see anyone else recommending it should be used to atomically increment a counter, but I believe RFC 2068 says it all very well:
The PATCH method is similar to PUT except that the entity contains a
list of differences between the original version of the resource
identified by the Request-URI and the desired content of the resource
after the PATCH action has been applied. The list of differences is
in a format defined by the media type of the entity (e.g.,
"application/diff") and MUST include sufficient information to allow
the server to recreate the changes necessary to convert the original
version of the resource to the desired version.
So, to update profile 123's view count, I would:
PATCH /profiles/123 HTTP/1.1
Host: www.example.com
Content-Type: application/x-counters
views + 1
Where the x-counters media type (which I just made up) is made of multiple lines of field operator scalar tuples. views = 500 or views - 1 or views + 3 are all valid syntactically (but may be forbidden semantically).
I can understand some frowning-upon making up yet another media type, but I humbly suggest it's more correct than the POST / PUT alternative. Making up a resource for a field, complete with its own URI and especially its own details (which I don't really keep, all I have is an integer) sounds wrong and cumbersome to me. What if I have 23 different counters to maintain?
An alternative might be to add another resource to the system to track the viewings of a profile. You might call it "Viewing".
To see all Viewings of a profile:
GET /profiles/123/viewings
To add a viewing to a profile:
POST /profiles/123/viewings #here, you'd submit the details using a custom media type in the request body.
To update an existing Viewing:
PUT /viewings/815 # submit revised attributes of the Viewing in the request body using the custom media type you created.
To drill down into the details of a viewing:
GET /viewings/815
To delete a Viewing:
DELETE /viewings/815
Also, because you're asking for best-practice, be sure your RESTful system is hypertext-driven.
For the most part, there's nothing wrong with using query parameters in URIs - just don't give your clients the idea that they can manipulate them.
Instead, create a media type that embodies the concepts the parameters are trying to model. Give this media type a concise, unambiguous, and descriptive name. Then document this media type. The real problem of exposing query parameters in REST is that the practice often leads out-of-band communication, and therefore increased coupling between client and server.
Then give your system a uniform interface. For example, adding a new resource is always a POST. Updating a resource is always a PUT. Deleting is DELETE, and getiing is GET.
The hardest part about REST is understanding how media types figure into system design (it's also the part that Fielding left out of his dissertation because he ran out of time). If you want a specific example of a hypertext-driven system that uses and doucuments media types, see the Sun Cloud API.
After evaluating the previous answers I decided PATCH was inappropriate and, for my purposes, fiddling around with Content-Type for a trivial task was a violation of the KISS principle. I only needed to increment n+1 so I just did this:
PUT /profiles/123$views
++
Where ++ is the message body and is interpreted by the controller as an instruction to increment the resource by one.
I chose $ to deliminate the field/property of the resource as it is a legal sub-delimiter and, for my purposes, seemed more intuitive than / which, in my opinion, has the vibe of traversability.
I think both approaches of Yanic and Rich are interresting. A PATCH does not need to be safe or indempotent but can be in order to be more robust against concurrency. Rich's solution is certainly easier to use in a "standard" REST API.
See RFC5789:
PATCH is neither safe nor idempotent as defined by [RFC2616], Section
9.1.
A PATCH request can be issued in such a way as to be idempotent,
which also helps prevent bad outcomes from collisions between two
PATCH requests on the same resource in a similar time frame.
Collisions from multiple PATCH requests may be more dangerous than
PUT collisions because some patch formats need to operate from a
known base-point or else they will corrupt the resource.