ngcp-panel/share/templates/api/root/collection.tt

<h[% level %] id="[% id %]">
  [% IF uri -%]
  <a href="[% uri %]" rel="collection">
  [% END -%]
  [% title %]
  [% IF uri -%]
  </a>
  [% END -%]
</h[% level %]>

[%- curl_auth_string = '';
    IF is_admin_api;
      curl_auth_string = '--cert NGCP-API-client-certificate.pem --cacert ca-cert.pem ';
    END; -%]

<h[% level + 1 %]>Description</h[% level + 1%]>

[% col.description %]

[% MACRO get_props_plain BLOCK ;
    IF col.sample.default || (action && col.sample.${action});
        IF col.sample.default && (!action || !col.sample.${action});
            props_plain = col.sample.default _ "\n";
        ELSE;
            props_plain = col.sample.${action} _ "\n";
        END;
    ELSE;
        #props_plain = '"id" : 1';
        props_creation_first_flag = 1;
        FOREACH p IN col.fields;
            NEXT IF p.types.0 == 'null';
            NEXT IF p.type_original == 'Upload';
            IF props_creation_first_flag;
                props_creation_first_flag = 0;
            ELSE;
                props_plain = props_plain _ ",\n";
            END;
            IF p.types.0 == "Number";
              val = 4;
            ELSIF p.types.0 == "String";
              val = '"test"';
            ELSIF p.types.0 == "Boolean";
              val = 'true';
            ELSIF p.types.0 == "Array";
              val = '[]';
            ELSE;
              val = '"missing"';
            END;
            props_plain = props_plain _ '"' _ p.name _ '" : ' _ val;
        END;
        props_plain = props_plain _ "\n";
    END;
    props_plain;
END;
%]
[%-
    FOREACH p IN col.uploads;
        #NEXT IF p.types.0 == 'null';
        uploads_form = uploads_plain _ ' --form \'' _ p.name _ '=@/path/to/' _ p.name _ '/file\'';
        uploads_data = uploads_data _ '"' _ p.name _ '" => [\'/path/to/' _ p.name _ '/file\']' _ ( !loop.last() ? ",\n" : "" );
    END;
%]

<h[% level + 1 %]>Collection Actions</h[% level + 1%]>
Allowed methods for the collection as in <span>METHOD [% uri %]</span>:
[% UNLESS col.actions.size -%]
<br/>None.
[% ELSE -%]
<ul id="[% id %]-actions">
    [% FOR a IN col.actions -%]
    <li>[% a %]</li>
    [% END -%]
</ul>
[% END -%]

<h[% level + 1 %]>Item Actions</h[% level + 1%]>
Allowed methods for a collection item as in <span>METHOD [% uri %]id</span>:
[% UNLESS col.item_actions.size -%]
<br/>None.
[% ELSE -%]
<ul id="[% id %]-itemactions">
    [% FOR a IN col.item_actions -%]
    <li>[% a %]</li>
    [% END -%]
</ul>
[% END -%]


<h[% level + 1 %]>Properties</h[% level + 1%]>
[% UNLESS col.fields.size -%]
See description how to obtain properties, if any.
[% ELSE -%]
<ul id="[% id %]-props">
[% FOREACH f IN col.fields -%]
    <li><b>[% f.name %] </b>(<i>[% f.types.join(', ') | html %]</i>): [%IF f.readonly %]<b>Readonly</b>. [%END%][% f.description | html %]</li>
[% END -%]
</ul>
[% END -%]

<h[% level + 1 %]>Query Parameters</h[% level + 1%]>

<ul id="[% id %]-qparams">
[% FOREACH f IN col.query_params -%]
    <li><b>[% f.param %]</b>: [% f.description %]</li>
[% END -%]
    <li><b>order_by</b>: Order collection by a specific attribute. Possible values are: <i>[% col.sorting_cols.join(', ') %]</i></li>
    <li><b>order_by_direction</b>: Direction which the collection should be ordered by. Possible values are: <i>asc (default), desc</i></li>
</ul>

<h[% level + 1 %]>Examples</h[% level + 1 %]>
<div class="examples">

[% IF col.actions.grep('^OPTIONS$').size -%]
<h[% level + 2 %]>Request available HTTP methods on the URI</h[% level + 2 %]>
<p>
[%
    cmd = 'curl -i -X OPTIONS -H \'Connection: close\' '_ curl_auth_string _'https://example.org:1443' _ uri;
    INCLUDE helpers/api_command.tt cmd=cmd level=level+3;

    request = 
'OPTIONS /api/' _ id _ '/ HTTP/1.1';

    response = 
'HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS, POST
Accept-Post: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/#rel-' _ id _ '"';
    INCLUDE helpers/api_req_res.tt request=request response=response  level=level+3;
-%]
</p>
[% END -%]

[% IF col.actions.grep('^GET$').size -%]
<h[% level + 2 %]>Request the entire <i>[% id %]</i> collection</h[% level + 2 %]>
<p>
<p>
    You cannot request the entire collection at once, but instead you can simply page through the results. The response provides <i>prev</i> and <i>next</i> links you can follow to get the next page.

    To define the page number and the rows per page to return, you can pass the parameters <i>page</i> and <i>rows</i>. Default values are <i>page=1</i> and <i>rows=10</i>, if you do not provide them.
</p>
[%
    cmd = 'curl -i -X GET -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/?page=1&rows=1\'';
    INCLUDE helpers/api_command.tt cmd=cmd level=level+3;

    props = get_props_plain() | indent(12);

    request =
'GET /api/' _ id _ '/?page=1&rows=1 HTTP/1.1';
    response =
'HTTP/1.1 200 OK
Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/"

{
   "_embedded" : {
      "ngcp:' _ id _ '" : [
         {
            "_links" : {
               "collection" : {
                  "href" : "/api/' _ id _ '/"
               },
               "curies" : {
                  "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
                  "name" : "ngcp",
                  "templated" : true
               },
               "profile" : {
                  "href" : "http://purl.org/sipwise/ngcp-api/"
               },
               "self" : {
                  "href" : "/api/' _ id _ '/1"
               }
            },
' _ props _ '         },
      ]
   },
   "_links" : {
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "next" : {
         "href" : "/api/' _ id _ '/?page=2&rows=1"
      },
      "ngcp:' _ id _ '" : [
         {
            "href" : "/api/' _ id _ '/1"
         },
      ],
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp-api/"
      },
      "self" : {
         "href" : "/api/' _ id _ '/?page=1&rows=1"
      }
   },
   "total_count" : 100
}';

    INCLUDE helpers/api_req_res.tt request=request response=response level=level+3;
-%]
<p></p></p>
[% END -%]

[% IF col.item_actions.grep('^GET$').size -%]
<h[% level + 2 %]>Request a specific <i>[% id %]</i> item</h[% level + 2 %]>
<p>

[%
    cmd = 'curl -i -X GET -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/1\'';
    INCLUDE helpers/api_command.tt cmd=cmd level=level+3;

    props = get_props_plain() | indent(3);

    request =
'GET /api/' _ id _ '/1 HTTP/1.1';
    response =
'HTTP/1.1 200 OK
Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/"
Link: </api/' _ id _ '/>; rel=collection
Link: <http://purl.org/sipwise/ngcp-api/>; rel=profile
Link: </api/' _ id _ '/1>; rel="item self"

{
   "_links" : {
      "collection" : {
         "href" : "/api/' _ id _ '/"
      },
      "curies" : {
         "href" : "http://purl.org/sipwise/ngcp-api/#rel-{rel}",
         "name" : "ngcp",
         "templated" : true
      },
      "profile" : {
         "href" : "http://purl.org/sipwise/ngcp-api/"
      },
      "self" : {
         "href" : "/api/' _ id _ '/1"
      }
   },
' _ props _ ' }';

    INCLUDE helpers/api_req_res.tt request=request response=response level=level+3;
-%]
</p>
[% END -%]

[% MACRO request_macro BLOCK ;
    IF http_request == 'POST' ;
        action = 'create';
        response = 'HTTP/1.1 201 Created';
        IF !col.properties.asynchronous ; 
            response = response _ '
Location: /api/' _ id _ '/2' ; 
        END ;
    ELSIF http_request == 'PUT' ;
        action = 'update';
        item_id = 2;        
        request_headers = "\nPrefer: return=minimal";        
        request_headers_form = ' -H \'Prefer: return=minimal\'';        
        response =
'HTTP/1.1 204 No Content
Preference-Applied: return=minimal';
    END;

    props = get_props_plain( action => action) | collapse;
    uploads_form = uploads_form | collapse;
    content_type = col.config.action.${http_request}.ContentType.0 ? col.config.action.${http_request}.ContentType.0 : 'application/json';

    IF content_type == 'multipart/form-data' ;
        request_data_plain = '\'json={' _ props _ '}\' ';
        props = get_props_plain( action => action) | indent(6);
        uploads_data = uploads_data | indent(3);
        request_data = "{\n   json => {\n" _ props _ ( uploads_data ? "   }\n" _ uploads_data : "" ) _ "\n}";
        request_form = ' --form ' _ request_data_plain _ uploads_form ;
    ELSE;
        request_data_plain = '\'{' _ props _ '}\'';
        props = get_props_plain( action => action) | indent(3);
        uploads_data = uploads_data | indent(0);
        request_data = "{\n" _ props _ ( uploads_data ? "\n" _ uploads_data : "" ) _ "}";
        request_form = ' --data-binary ' _ request_data_plain _ uploads_form;
    END;
    


    cmd = 'curl -i -X ' _ http_request _ ' -H \'Connection: close\' -H \'Content-Type: ' _ content_type _ '\'' _ request_headers_form _ ' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/' _ item_id _ '\' ' _ request_form ;
    
    request =
http_request _ ' /api/' _ id _ '/' _ item_id _ ' HTTP/1.1
Content-Type: ' _ content_type _ request_headers _ '

' _ request_data;

    
    INCLUDE helpers/api_command.tt cmd=cmd level=level+3 extended=http_request == 'PUT';
    INCLUDE helpers/api_req_res.tt request=request response=response level=level+3;
END%]

[% IF col.actions.grep('^POST$').size -%]
<h[% level + 2 %]>Create a new <i>[% id %]</i> item</h[% level + 2 %]>
<p>
[%
    request_macro(http_request = 'POST');
%]
</p>
[% END -%]

[% IF col.item_actions.grep('^PUT$').size -%]
<h[% level + 2 %]>Update an existing <i>[% id %]</i> item</h[% level + 2 %]>
<p>
[%
    request_macro(http_request = 'PUT');
-%]
</p>
[% END -%]

[% IF col.item_actions.grep('^PATCH$').size -%]
<h[% level + 2 %]>Update specific fields of an existing <i>[% id %]</i> item</h[% level + 2 %]>
<p>
[%
    props = ''; rem = 0; rep = 0;
    FOREACH p IN col.fields;
        NEXT IF col.sample_orig && col.sample_orig.update && ( col.sample_orig.update != 'default' ) && ( !col.sample_orig.update.${p.name} );
        type = p.types.0;
        IF type == 'null';
            NEXT IF rem >= 1;
            op = "remove";
            type = p.types.1;
            rem = rem + 1;
        ELSE;
            NEXT IF rep >= 1;
            op = "replace";
            rep = rep + 1;
        END;

        IF type == "Number";
          val = 5;
        ELSIF type == "String";
          val = '"other"';
        ELSIF type == "Boolean";
          val = 'false';
        ELSIF type == "Array";
          val = '[]';
        ELSE;
          val = '"missing"';
        END;
        props = props _ '{ ';
        props = props _ '"op" : "' _ op _ '", "path" : "/' _ p.name _ '"';
        UNLESS op == "remove";
            props = props _ ', "value" : ' _ val;
        END;
        props = props _ ' }, ';
        LAST IF rep >= 1 && rem >= 1;
    END;
    props = props.substr(0, props.length - 2);

    cmd = 'curl -i -X PATCH -H \'Connection: close\' -H \'Content-Type: application/json-patch+json\' -H \'Prefer: return=minimal\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/2\' --data-binary \'[ ' _ props _ ' ]\'';
    INCLUDE helpers/api_command.tt cmd=cmd extended=1 level=level+3;
%]

<p>
    The PATCH method allows to operate on specific fields of an item. The <b>path</b> attribute can point to a normal property (e.g. /something) or to a specific element in an array (e.g. /something/0). Available <b>op</b> values are:
    <ul>
        <li>
            <b>remove</b>
            <p>Removes the property pointed to by <b>path</b>. You can point to a normal property (e.g. /something) or to a specific element in an array (e.g. /something/0).</p>
        </li>
        <li>
            <b>replace</b>
            <p>Replaces the value pointed to by <b>path</b> by the new value passed via <b>value</b>.</p>
        </li>
        <li>
            <b>add</b>
            <p>Adds a new property <b>path</b> by the new value passed via <b>value</b>.</p>
        </li>
        <li>
            <b>copy, move</b>
            <p>Copies or moves (copy, then remove) the value from property defined by <b>from</b> to the propery defined by <b>path</b>.</p>
        </li>
    </ul>
</p>

[%
    props = ''; rem = 0; rep = 0;
    FOREACH p IN col.fields;
        NEXT IF col.sample_orig && col.sample_orig.update && ( !col.sample_orig.update.${p.name} );
        type = p.types.0;
        IF type == 'null';
            NEXT IF rem >= 1;
            op = "remove";
            type = p.types.1;
            rem = rem + 1;
        ELSE;
            NEXT IF rep >= 1;
            op = "replace";
            rep = rep + 1;
        END;

        IF type == "Number";
          val = 5;
        ELSIF type == "String";
          val = '"other"';
        ELSIF type == "Boolean";
          val = 'false';
        ELSIF type == "Array";
          val = '[]';
        ELSE;
          val = '"missing"';
        END;
        props = props _ '
  {
';
        props = props _ '    "op" : "' _ op _ '",
    "path" : "/' _ p.name _ '"';
        UNLESS op == "remove";
            props = props _ ',
    "value" : ' _ val;
        END;
        props = props _ '
  }, ';
        LAST IF rep >= 1 && rem >= 1;
    END;
    props = props.substr(0, props.length - 2);

    request =
'PATCH /api/' _ id _ '/2 HTTP/1.1
Content-Type: application/json-patch+json
Prefer: return=minimal

[' _ props _ '
]';
    response =
'HTTP/1.1 204 No Content
Preference-Applied: return=minimal';

    INCLUDE helpers/api_req_res.tt request=request response=response level=level+3;
-%]
<p></p></p>
[% END -%]

[% IF col.item_actions.grep('^DELETE$').size -%]
<h[% level + 2 %]>Delete a specific <i>[% id %]</i> item</h[% level + 2 %]>
<p>

[%
    cmd = 'curl -i -X DELETE -H \'Connection: close\' '_ curl_auth_string _'\'https://example.org:1443/api/' _ id _ '/1\'';
    INCLUDE helpers/api_command.tt cmd=cmd level=level+3;

    request =
'DELETE /api/' _ id _ '/1 HTTP/1.1';
    response =
'HTTP/1.1 204 No Content';

    INCLUDE helpers/api_req_res.tt request=request response=response level=level+3;
-%]
</p>
[% END -%]

</div>

[% IF col.journal_resource_config.journal_resource_enabled -%]
<h[% level + 1 %]>Journal</h[% level + 1%]>
A collection showing the history of modifications to a particular [% title %] collection item can be accessed using <span>OPTIONS/GET/HEAD [% col.journal_resource_config.uri %]</span>. By configuration, CRUD operations below will be recorded:
[% UNLESS col.journal_resource_config.operations.size -%]
<br/>None.
[% ELSE -%]
<ul id="[% id %]-journal_operations">
    [% FOR o IN col.journal_resource_config.operations -%]
    <li>[% o %]</li>
    [% END -%]
</ul>
[% END -%]
Query parameters:
<ul id="[% id %]-journal_qparams">
[% FOREACH f IN col.journal_resource_config.query_params -%]
    <li><b>[% f.param %]</b>: [% f.description %]</li>
[% END -%]
    <li><b>order_by</b>: Order collection by a specific attribute. Possible values are: <i>[% col.journal_resource_config.sorting_cols.join(', ') %]</i></li>
    <li><b>order_by_direction</b>: Direction which the collection should be ordered by. Possible values are: <i>asc (default), desc</i></li>
</ul>
The item's state after a completed create or update operation/before a delete operation is serialized and stored in [% col.journal_resource_config.format -%] format. It can be retrieved by requesting the corresponding journal record with <span>OPTIONS/GET/HEAD [% col.journal_resource_config.item_uri %]</span>.
[% IF col.journal_resource_config.recent_uri -%]
The most recent journal record is directly accessible using <span>OPTIONS/GET/HEAD [% col.journal_resource_config.recent_uri %]</span>.
[% END -%]
[% END -%]

[% # vim: set tabstop=4 syntax=html expandtab: -%]