RESTFul URI parameter limitations/bugs

TobiasE wrote:
Hi,

I've run into some limitations (or bugs, don't know which is the most appropriate term at this point) regarding URI template parameters for RESTful Services. Here are a few examples to illustrate:

First limitation:

To start with, I define the following Resource Template: *example?p1={p1}&p2={p2}*
I use the following query as the GET handler: select :p1, :p2 from dual
This works fine, the URI example?p1=foo&p2=bar gets a json response like this: {":1": "foo",":2": "bar"}

I then create a second Resource Template with only the first parameter from the previous template: *example?p1={p1}*
I use the following query as the GET handler: select :p1 from dual
This works as expected, however now the previous template returns the following: {":1": "foo&p2=bar"}, i.e. the part of the URI string after p1= gets parsed as a single parameter.

Second limitation:

I define the following resource template: *example1/{p1}*
I use the following query as the GET handler: select :p1 from dual
Works fine.

I then define the following resource template: *example1/{p1}/example2*
I use the same query again as the GET handler: select :p1 from dual. This time the whole part of the URI string from {p1} forward gets parsed as the p1 parameter, which means it returns {":1":"foo/example2"} rather than {":1":"foo"}. However, if I remove the example1/{p1} template, the example1/{p1}/example2 works as expected.

In both cases, it seems like the rules for URI templates are excessively strict regarding URI similarities with other templates. I've been unable to find any reference to this in the documentation, other than a vague reference to a lack of support for "optional parameters".

Assuming these are known limitations rather than bugs, might they be removed in a future release?

TobiasE wrote:
thank you very much for your thorough reply. Everything's working great when I set different priority values, I hadn't realized that's what the priority field is for (although now that I check, it's actually stated pretty clearly in the SQL Workshop Guide for APEX 4.2). Just one minor niggle: in the APEX help text for the Priority field, it says "Lower numbers are evaluated first.", which seems to be the opposite of what actually happens.

Having read the above thread I'm still not 100% sure whether the API presently supports optional paramaters. Ie I've got URI templates set up at the moment with 5 or 6 variables that could be passed into some of them. At the moment I'm assuming that it is mandatory to state every variable when calling the method (even if you actually only need in some calls to set 1 or 2 variables). Is this the case?

Thanks

Simon

Hi.

A couple of questions/thoughts regarding the parsing of URI templates. I am a bit new in this area so please bear with me.

1)

From the above post:

"The answer is it chooses the one with the highest priority, but if they are both the same priority, then (and admittedly this isn't documented anywhere, it may be subject to change in future releases) it chooses the resource template that requires the least number of parameters to achieve a match..."

Why is it implemented like this?

If one has two different requests like

a) example?p1=foo&p2=bar

b) example?p1=foo

then, to me, request a) is more specified than request b) and should therefore be used (otherwise, why did caller supply parameter p2?).

2)

From the above post:

"The important thing to realise is that a URI Template matches any characters, characters which you might assume are significant to the matching algorithm, the characters which act as delimiters in the URI and query string syntax are not treated as delimiters, they have no special significance, *&*,*=*,*/*,*?* are all treated just the same as any other character ."

Without the time to dig in to all the details in APEX REST or RFC 6570, I believe that the way I have to implement the different kind of templates gets kind of tedious. For some reason (I can't figure out why), the templates have to make exact matches of all the possible URI's? If one compares this to some ordinary web server parsing, this is not the case I believe. I am free to request example?p1=foo&p4=bar, or example?p2=bar&p1=foo&p7=foobar etc. The different requests get parsed and the parameters get expanded.

The web server approach sounds like this snippet from the RFC:

RFC 6570:

"The URI Template syntax has been designed to carefully balance the

  need for a powerful expansion mechanism with the need for ease of

  implementation. The syntax is designed to be trivial to parse while

  at the same time providing enough flexibility to express many common

  template scenarios."

In my latest APEX REST application I hade like 7-9 parameters, and the number of templates should have been too large for me. Instead I implemented the example?{params} template and parsed the parameters myself by something like

v_array1 := apex_util.string_to_table(p_params, '&');
for i in 1..v_array1.count loop
    v_array2 := apex_util.string_to_table(v_array1(i), '=');
    case v_array2(1)
        when 'p1' then p_1 := v_array2(2);
        when 'p2' then p_2 := v_array2(2);
        when 'p3' then p_3 := v_array2(2);
        when 'p4' then p_4 := v_array2(2);
        ...
    end case;
end loop;

In the case of the example?... template, could one not in the APEX REST api have some list of possible parameters that get taken care of, like the header binding?

Br Peter

I was about to drop the apex listener restful service when I found this blog that solved all my issues, this template matching based on priority subtility should really be highlighted in the doc. I am glad to find this very good explanation. What should also be improved in the doc, in fact in the nice demo application, is to demonstrate with POST/PUT/DELETE and not only with GET

What I could not implement (I had to use workaround) was to change the http result code (for ex. 201 for resource created). Also when doing a post, I would like to send back the update record in the response but this is not possible to have output parameters with the same name as the input variables sent with the request. There are in/out parameters but only in the http headers.

Thanks and regards,

Pierre

Hi Pierre

(I know this is a bit late,  but decided to put it here for future problem searching users)

You can set the status code in two ways. 

1. Assuming POST and PL/SQL
   1. create an OUT parameter "HTTP Header" -> Parameter type: Integer  -> Name: X-APEX-STATUS-CODE -> Bind variable name: status
      1. Then set it simply with:  :status := 201;
   2. Use owa_util.  Example:
      1. owa_util.status_line (201);
      2. owa_util.status_line (401);
2. As for returning an id back.  I personally simply use htp.p to return a json string in the body which I can then parse.
   1. example:  htp.p ('{"status": "ok", "id":' || l_pid || '}');

Regards

Oli

Thanks Oli, I did not see that before, I will try to make use of it. As for using htp.p it is a good idea, I will do that for the POST where the client (an angular application) expect to receive the persisted data in the response body. It did not occur to me it would be so simple :-).

I did not suceed in doing a file upload via a APEX REST interface (there is an example in the doc though, but it is very circumvulated), so I tried to port my application to nodejs using the node-oracle driver and I found it very easy and efficient, But apex restful services is still the fastest way to deliver, for sure. I hope I'll get other chances to practice it again.

Rgds, Pierre