The API object defines an Application Programming Interface of a set of programs like Data Providers and Procedures.
It is meant for modeling an API mediation layer that clearly separates the interface from the implementation and so facilitates incremental development and the management of the evolution of an API.
An API object groups several services that are semantically and functionally related. For each service, it declares a mapping between its external name (exposed as a service) and the internal implementation in the KB. It features flexibility in terms of service declaration, allowing the configuration of the HTTP method to be used when the service is REST. It also allows indicating the name and type of the parameters, offering great flexibility in parameter transformation.
The API interface is declared in the 'Service Source' part of the object.
For each service of the interface, you can declare:
- Name
- Parameters
- Which GeneXus object contains the implementation and with what parameters it is called
- Annotations for protocol-specific options.
The API object allows you to expose an API for the following protocols:
At the object level, you have properties to enable each of them.
(*) The gRPC protocol is not supported in the .NET Generator. It is in beta state in .NET Core and Java.
Events can be defined in the 'Events' part of the object.
This is where you can do the following:
- Program data transformations to the service parameters, before and after calling the object that implements the service, which helps to maintain a stable API
- Manage traffic, analyze it, apply service policies. That is, for example, count service calls, log them, accept or deny access to your API.
For each API object, you can define a 'Before' and 'After' event, which will be executed before and after each service implementation.
In addition, for each service you can define '<service name>.Before|After' events. So, every time a service is invoked, the following will be executed:
- Event 'Before'
- Event '<service>.Before'
- The object corresponding to the implementation of the service, referenced in the 'Service Source'
- Event '<service>.After'
- Event 'After'
Database access is not allowed in Events; that kind of logic should be placed in the called Procedures or Data Providers.
Here you can define the variables to be used in the Source and Events.
There are some standard variables of each API object:
- &Pgmname - It contains the name of the object
- &Pgmdesc - It contains the description of the object
- &RestMethod - It contains the HTTP Method with which the object was called. It is empty when the object is called using protocols other than REST
- &RestCode - You may set it to customize the returned HTTP Status Code
These are the properties that can be set at the object level:
This sample showcases the API called 'Client' with services to list clients, get details of a specific client, and insert a client.
This is the 'Service Source' part of the API object:
Client{
List(out:&SDTClients)
=> Core.ClientsList(&ClientCategoryCode,&SDTClients);
GetByKey(in:&ClientId,out:&Client,out:&Messages)
=> Core.ClientGetbyKey(&ClientId,&Client);
[RestMethod(POST)]
Insert(in:&ClientId,in:&ClientName,in:&ClientAddress,out:&Messages)
=> Core.ClientInsert(&ClientId,&ClientName,&ClientAddress,&Messages);
}
Note:
- When accessed through the Rest Protocol, List and GetByKey are accessed via HTTP 'GET' Method, and Insert is accessed via 'POST' declared with the '[RestMethod(POST)]' annotation
- Service parameters have to be declared as in or out
- Parameter mapping and parameter value transformations can be done using the 'Events' part as shown below
- Overloading of services (Using the same service name for different Rest Methods as it is usual in REST Services) is possible in APIs that are only exposed as REST
- For the REST protocol, the URI is as shown below:
URLBase/ModuleName/ApiObjectName/Method
So, in this sample, it is similar to the following:
URLBase/Core/Client/List
This is the 'Events' part:
Event Before
Statsregister(&pgmname)
EndEvent
Event List.Before
&ClientCategoryCode = 'Any'
EndEvent
Event Insert.Before
if &ClientId <= 0
&RestCode = 412
return
endif
EndEvent
Event GetByKey.After
if &Client.ClientId = 0
&Message.Type = MessageTypes.Error
&Message.Description = format("Client %1 was not found",&ClientId)
&Messages.Add(&Message)
&RestCode = 404
endif
EndEvent
Notes:
- 'List.Before' initializes a variable that is not part of the API but that is required by the called object
- The procedure associated with the Insert service (and the Insert.After event) in this sample will only be executed if &ClientId > 0
You can download the source of this sample from here
When Generate OpenAPI interface property is enabled, GeneXus generates a .yaml with the OpenAPI specification for each API object. That file (named <apiobject's qualified name>.yaml) contains all the information related to the services exposed by the API.
Parameters in the query string (input parameters of the services) are named, separated by &, and are also case-sensitive in Java. Therefore, if you consume the API, make sure to name them using the casing declared in the .yaml so that your consumer does not depend on the generator used to provide the services.
- To avoid compatibility issues and interface stability, do not use the SDT you use in the interface of an API Object also in services of another kind (Rest Data Providers, Rest Procedures, Rest Business Components)
- Do not use in an interface a variable marked as a collection, since in that case, you cannot set the Json Collection Serialization property. If you need to return a collection, define the SDT as collection and define de variable based on that SDT.
This feature is available in .NET and .NET Core in GeneXus 17, and in Java in GeneXus 17 upgrade 2.
In GeneXus 17 upgrade 1, &RestCode standard variable has been added.