Build a server-side RESTful API with Coldbox (Merapi)

We are going to build a Coldbox REST API and test it using the TestBox module. We shall document this API by adding annotations to our API handlers. We'll then use the Coldbox cbSwagger module to generate our API documentation in the Swagger Editor. Finally, we'll use Postman to input data in order to simulate API responses from calls to our development server.

Please note however, that it is not in the scope of this course to explain Swagger Editor and Postman tools in detail. Also note that  API security issues using Coldbox cbSecurity and JWT (Json Web Tokens) won't  be discussed in this course. Last and not least, we won't build and connect a javaScript front-end to this server-side API.

We are first going to add tables to our MySQL database schema called Merapi (4 tables altogether) , build relationships between those tables and populate our tables with seed data with the help of Coldbox cfmigrations module. This database schema manages data about Countries, Currencies, Cities and Airports. The cfmigrations module was already covered in detail in my two earlier tutorials, but will be covered again at the beginning of this tutorial and documented in the guide provided with it.

Next, we are going to build our model and map our entity class property names to our tables columns name using an XML schema file representing the database schema. We'll also have an XML Loader file to read the XML schema, thus implementing a simple custom object relational mapper.  This approach is an alternative, to what we demonstrated in another course called Tamarind v1, in which we used Quick ORM to map entity object properties to table columns and to load entities in memory. Therefore, in this course, no ORM is involved.

We also leveraged object inheritance with the creation of a BaseService parent component. Like a DAO (Data Access Object), this component provides an abstraction of our queries for READ, DELETE and record filtering methods. This way, there is no need to write those queries again in the children components. We simply call the relevant method from the BaseService parent component with the Super keyword.

To make sure that our model entity and services are fully functional, we shall use the Testbox module to write unit tests. After completing our model entity and service components and making sure all our unit tests pass, we shall focus on building the API itself. The API is going to deal with two types of things: the API handlers and the API documentation.

The handlers are composed of actions (index, show, create, update and delete). As we write our handlers, we shall also write the corresponding integration tests that guarantee that our handlers are working fine. Integration tests will also be written with Testbox. 

The API documentation is composed of json files such as responses, requestBody, parameters and examples that apply to each handler's action based on an API response such as 2xx (Success), 4xx (Not found or validation error) or 5xx (Server error). A pointer to each of these json files found in the /apidocs folder, will be added as an annotation to the handler's action code. Thanks to this, our API documentation will become immediately exportable to tools such as Postman or OpenAPI (Swagger).

Once this is done, we shall leverage the Coldbox cbswagger module to generate an output as we hit our development server url at cbswagger. Copying and pasting this cbwagger output in our Swagger Editor will not only deliver a colourful and neat documentation of our API, but also generate an openAPI.yaml file that we can then import into Postman. Postman is a tool that allows further testing of our API server with real data.

At the end of the course, you should have acquired a solid and practical understanding as how to build a server-side REST API with the Coldbox framework.