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.