Page History

Table of Contents

Intro

Since you develop API you need endpoints and controllers. Endpoint is a point at which an API (the code that allows two software programs to communicate with each other) connects with the software program. Due to writing an endpoint is a routine, JBT allows to reduce boilerplate code. Controller's main aim is to accept an input and to convert it to commands for the model or view. Since you work with API, view is an endpoint. 

JBT uses XML-files for describing controllers, endpoints and models. Then it uses such files for Java-code generation. As a result you get API based on MVC pattern written on Java. Let's start.

Controller

Creating

First of all, you need to create a controller. Let's take an API for working with companies as an example.

...

IMPORTANT: controller must have exactly the name specified above. Also folder must be created using the path specified above.

Describing

The file must contain the following tags:

...

There are 'jwt', 'basic' and 'apiKey' with true/false values among other optional attributes in tag <private>. You can find more info about these attributes and their purpose here.

Example

Description example for a controller is given below:

<controller xmlns="http://www.knubisoft.com/api/schema/controller">
    <overview>
        <description>
            Company API
        </description>
    </overview>

    <public>
        <include value="getCompany"/>
        <include value="getEmployee" weight="2"/>
    </public>

    <private alias="baseRights">
        <include value="addFirmInformation"/>
        <include value="getFirmInformation"/>
        <include value="addCreditCard"/>
        <include value="updateInformation"/>
    </private>
</controller>

Endpoint

Basically, you have different operations in your API. In our case it can be adding a credit card, adding a company info, getting that info or updating it. Since all these actions are different operations, you need to create different endpoint for it. Let's take adding a company info as en example.

Creating

Firstly, you need to create a folder which represents desired operation on the same level as controller.xml was created (in our case it's api/api-spec/src/main/resources/spec/api/company/addFirmInformation). Then put in that directory a file named 'endpoint.xml'

IMPORTANT: the name should be exactly 'endpoint.xml'.

Describing

Your endpoint should starts with <endpoint> tag. It must contain the following tags:

...

<post> tag in addition to <get> functions may contain a model which should be sent during executing POST request to the endpoint. So it can contain both <response> and <request> tags. As a <response> tag above, <request> tag can contain info about the model in 'include' attribute (file should be situated in the place mentioned above) or in the same folder as endpoint.xml in the file named 'request.xml' (in case of empty tag).

Example

<endpoint xmlns="http://www.knubisoft.com/api/schema/endpoint">

	<swagger>
		<operationId>addFirmInformation</operationId>
		<summary>Add firm information</summary>
		<description>Add firm information</description>
		<tags>
			<tag>Company</tag>
		</tags>
	</swagger>

	<post>
		<response include="firmInformationResponse.xml"/>
		<request/>
	</post>

</endpoint>

Response & request

Both response and request mostly contain an information about an object to which API is intended to work with. So usually it is different data like company name, number of employees, dates of contracts establishment and so on. And all these data can be described in response/request.

Creating

You can create file 'response.xml' ('request.xml') right in the folder where your endpoint.xml is placed (in such case you needn't use 'include' attribute in appropriate tags in endpoint.xml) or you can create it in folder spec/src/main/resources/spec/__def__/models/static and pass its name to 'include' attribute of appropriate tag in endpoint.xml. No matter what you choose, it's up to you.

Describing

For both response and request you need to use tag <class>. It can contain

...

IMPORTANT: your name for a class must be written using PascalCase and end with 'Request'/'Response'.

Example

<class name="FirmInformationRequest" xmlns="http://www.knubisoft.com/api/schema/class" >
	<string name="firmName" description="Firm name"/>
	<string name="country" description="Country"/>
	<string name="state" description="State"/>
	<string name="city" description="City "/>
	<string name="firstAddress" description="First address"/>
	<string name="secondAddress" description="Second address"/>
	<integer name="postCode" description="Post code"/>
	<localdate name="establishDate" description="The date of establishing"/>
</class>

Put it all together

As a result you should get the following structure:

...