REST Web services APIs

High-level and low-level REST APIs

REST Web services implemented with the high-level framework outweigh a low-level solution in terms of ease of creation. A summary of each API is given next.

REST high-level APIs

Web services implemented with the high-level REST framework use the Function attributes feature to define details of the Web service. Function attributes are specified in an ATTRIBUTES() clause of the function to define operation type, and path. Attributes also define parameters for path template, query strings, return values, etc., of your RESTful Web service function. These special attributes for REST high-level define the framework for creating REST web services.

Web service function attributes are identified with the WS* prefix. For example, the sample function add, is defined on the server side using the attributes, WSGET, WSQuery, WSPath, and WSDescription.

These define the resource's endpoint (/add) that the API exposes, the GET HTTP method used, and the values expected in the query string.

PUBLIC
# Query sample
FUNCTION Add(a INTEGER ATTRIBUTES(WSQuery), b INTEGER ATTRIBUTES(WSQuery))
  ATTRIBUTES (WSGET, WSPath='/add', WSDescription='Simple query sample')
  RETURNS (INTEGER)
  RETURN a + b
END FUNCTION

When you need to determine what functions are available on the server, you can use the fglrestful tool (server side), to get all of the information necessary in an OpenAPI specification file (JSON or YAML). The fglrestful tool can also generate a stub file for the client.

REST low-level APIs

The standard HTTP classes HTTPRequest, HTTPResponse, and HTTPServiceRequest are available if you need to code individual commands. Be aware that you have to write all the HTTP code of your services by hand.

The client stub generated by the fglrestful tool implements low-level APIs.

When to use high-level REST APIs

The recommendation is to use the high-level APIs wherever possible to implement RESTful Web services because using the REST attributes in your function parameters require less code in your application. They provide functionality that would otherwise need to be handled with many low-level API calls.

When to use low-level REST APIs

You may opt to use low-level APIs when there is a need for more detailed and granular control, or you may opt to use them in specific scenarios because a high-level implementation may not yet be available.