Quickly Define APIDocAttributes To Easily Add Documentation To Your RAD Server Solutions

The sample consists of an EMS package that loads a new resource into the EMS Server provided with RAD Studio. The demo uses FireDAC components to access the Interbase database employee.gdb. The connection parameters are defined in the TFDConnection component. If you experience problems with the connection verify these parameters.

It requires InterBase to be installed on the machine or to connect to a remote server. Make sure that the server is running before you run the example. InterBase is used to store the information about the server connections. You can use the RAD Server Console to display the statistics.

Location

You can find the APIDocAttributes sample project at:

• Start | Programs | Embarcadero RAD Studio Sydney | Samples and then navigate to either:
  • Object PascalDataBaseEMSAPIDocAttributes
  • CPPDatabaseEMSAPIDocAttributes
• Subversion Repository:
  • You can find Delphi and C++ code samples in GitHub Repositories. Search by name into the samples repositories according to your RAD Studio version.

How to Use the Sample

Run the EMS Package

When you run the APIDocAttributes project, the EMSDevServer starts automatically. If the configuration file is missing, a wizard launches.

1. Navigate to the location given above and open:
   • Delphi: APIDocDelphiAttributes.dpk
   • C++: APIDocCppAttributes.cbproj
2. Press Shift+Ctrl+F9 or choose Run > Run Without Debugging.
3. The EMS Development Server opens. If it is the first time you are using EMS on the machine, you need to run the configuration wizard in order to create the EMS server configuration file.
   1. When the Confirm dialog opens, click Yes.
   2. Leave all the parameters by default and go through the different windows clicking Next.
   3. Click Finish to close the wizard.
   4. An Information window appears. Click OK.
4. The server starts automatically. Minimize it.

API Doc Attributes

The new EMS package loads a new resource in the EMS Server. The new resource contains four endpoints with their corresponding API documentation in YAML and JSON format.

To access the API documentation:

• http://localhost:8080/api/apidoc.yaml
• http://localhost:8080/api/apidoc.json

To access the API documentation only for the new resource uploaded:

• Delphi:
  • http://localhost:8080/api/sampleattributesdelphi/apidoc.yaml
  • http://localhost:8080/api/sampleattributesdelphi/apidoc.json
• C++:
  • http://localhost:8080/api/sampleattributescpp/apidoc.yaml
  • http://localhost:8080/api/sampleattributescpp/apidoc.json

To see the result of the SQL query in JSON format in the browser:

• http://localhost:8080/sampleattributesdelphi
• http://localhost:8080/sampleattributescppNote’: This response is obtained using the Get endpoint method of the new resource.

The structure of the result provided by the server is also provided in the API documentation, in the [EndPointObjectsYAMLDefinitions(Definition_schema)] and [EndPointObjectsJSONDefinitions(Definition_schema)].

Use GetItem to see one specific item of the employee table. To see how to use each specific method, you can access the API documentation provided.

• http://localhost:8080/sampleattributesdelphi/{item}
• http://localhost:8080/sampleattributescpp/{item}

Note: The GetItem method generates a new SQL query with the item FIRST_NAME provided.

SELECT * FROM EMPLOYEE WHERE FIRST NAME = {item}

For example:

http://localhost:8080/sampleattributesdelphi/Robert

{"FDBS":{"Version":15,"Manager":{"TableList":[{"class":"Table","Name":"EmployeeTable","SourceName":"EMPLOYEE","SourceID":1,"RowList":[{"RowID":0,"Original":{"EMP_NO":2,"FIRST_NAME":"Robert","LAST_NAME":"Nelson","PHONE_EXT":"250","HIRE_DATE":"20071229T000000","DEPT_NO":"600","JOB_CODE":"VP","JOB_GRADE":2,"JOB_COUNTRY":"USA","SALARY":105900,"FULL_NAME":"Nelson, Robert"}}]}]}}}

There are two more methods provided in the sample, Post and PutItem.

Use Post to update an item, and PutItem to add a new item into the employee table.

Implementation

EMS Package

The Resource Module has code to register a REST API resource. The resource is called “sampleattributesdelphi” or “sampleattributescpp”. The resource defines four methods: Get, GetItem, Post, and PutItem.

Once you run the package and have the EMS server running, as a test, you can invoke the GET method using the browser http://localhost:8080/sampleattributesdelphi.

The TDataModule contains the FireDAC components:

• FireDAC.Comp.Client.TFDConnection establishes the connection to the Interbase database.
• FireDAC.Comp.Client.TFDQuery contains an SQL query: “SELECT * FROM EMPLOYEE”.
• TFDSchemaAdapter is responsible for saving query results to JSON and for loading a JSON delta and applying inserts, updates, and deletions to the database.

Here is some sample source code showing the attributes:

To get more detailed information or links to other information, please visit the original post of Embarcadero:

http://docwiki.embarcadero.com/CodeExamples/Sydney/en/EMS.APIDocAttributes_Sample

Head over and check out the full source code for the APIDocsAttributes sample for RAD Server on GitHub.