Subroutine annotations
DataBasic subroutines called by RESTful services use annotations within the subroutine source to specify its interface to the realityrest URL.
An annotation section starts with @ANNOTATE RESTFUL and ends with @ANNOTATE END
Annotation lines have a simple structure of
* Name = value
Each line may contain an optional ; comment on the end. All white space in a line is superfluous and is removed before parsing.
A subroutine may have more than one annotate section, as long as they have different WPTR names, enabling parameters to be passed in different ways. It is also valid to have more than one subroutine specifying the same WPTR item, as long as they use different HTTP methods.
Name type keywords used in the annotation section include the following:
|
@MAPNAME |
The WPTR name to be used in the URL. |
|
@METHODS |
A comma separated list of HTTP methods supported. |
|
@MIMETYPE |
The default mime type returned by this subroutine. |
|
%name |
Assigns value to subroutine parameter name. |
|
@PARAMn |
Alternate to above assigns value to parameter n. |
|
@RETURN |
Sets the parameter to return the data (alternative to using HTTP_RETURN). |
The value type keywords used in the annotation section include the following:
|
@METHOD |
The HTTP method used. For example, %DATA = @METHOD; *assigns the HTTP method (GET, PUT, etc.) to the parameter DATA. |
|
@MAPNAME |
The WPTR name used to invoke this subroutine. %MAP = @MAPNAME; *assigns the WPTR name to the parameter MAP. |
|
@PATHn |
Path component n Path components starting after the mapping name, for example, …/realityrest/mydb/SALES/1234?type=json %DATA = @PATH1; * assigns 1234 to the parameter DATA |
|
@URL |
Supplied URL up to but not including mapping item name. |
|
@DATA |
Unprocessed PUT, POST, PATCH data. For example, %DATA = @DATA; * assigns post data to the parameter DATA. |
|
@MIMETYPE |
The MIME type of the incoming data. |
|
@HTTP_xxx |
The value of HTTP header xxx. For example, %TYPE = @HTTP_Pragma; * May set the parameter TYPE to “no-cache”. |
|
<name> |
A name not starting with @ extracts the value for name from the query string. For example, …/realityrest/mydb/SALES/1234?type=json %TYPE = type; * assigns 1 to the parameter TYPE |
|
%name |
Uses subroutine parameter name. For example, @RETURN = %FILE.NAME This is an alternative to using RW_RETURN subroutine. |
Note
The value type keywords are processed by RW_RESTFUL so syntax errors in value keywords may not be noticed until run time.
Example
As an example the subroutine GET.ITEM may have the following annotation. The subroutine parameters are specified in two different ways showing the @PARAMn and %name syntax:
001 SUBROUTINE GET.ITEM(FILE.NAME, IID, AUTHOR, HOST, DATA, TYPE) 002 * 003 * Call as 004 * .../realweb/realityrest/<rw_section>/ITEM/<file name>/<item name>?type=json 005 * 006 * For HTTP-SERVER use rw_section is not used but must be present. 007 * 008 * @ANNOTATE RESTFUL 009 * @MAPNAME = ITEM ; Name of mapping item 010 * @METHODS = GET, POST, PUT ; HTTP actions supported 011 * @MIMETYPE = application/text ; Default MIME type of data returned 012 * @PARAM1 = @PATH1 ; Using path syntax 013 * @PARAM2 = @PATH2 014 * @PARAM3 = @HTTP_Authorization ; Get HTTP input header 015 * @PARAM4 = @HTTP_Host 016 * %DATA = @DATA ; The Post data 017 * %TYPE = type ; Get query parameter type 018 * @RETURN = %FILE.NAME 019 * @END ANNOTATE 020 *
Note
It is standard RESTful practice not to code operations into the URL. So a URL like …/ITEM/FILE.NAME/NAME may result in a read, update or delete dependent on the HTTP method used.
The RESTful annotation mechanism enables one subroutine to handle multiple HTTP methods, or for each HTTP method to call a unique subroutine. Therefore, the ITEM WPTR may generate calls to GET.ITEM for the GET method, WRITE.ITEM for POST and PUT methods, and DELETE.ITEM for the DELETE method.