Project Introduction

In the previous chapter we built a complete admin CRUD interface for managing countries - forms, tables, pagination, search, and all the HTML views. In this chapter we take the same data and expose it through a RESTful API, returning JSON instead of HTML.

This is a common requirement: perhaps you are building a mobile app that needs to read country data, or you want to let a third-party service create records programmatically. By the end of this chapter you will have a fully functional JSON API with token-based authentication, input validation, proper HTTP status codes, and request logging.

What is a REST API?

REST (Representational State Transfer) is an architectural style for building web services. In a REST API, each URL represents a resource (such as a country), and HTTP methods represent actions on that resource:

• GET - Retrieve a resource or collection
• POST - Create a new resource
• PUT - Update an existing resource
• DELETE - Remove a resource

The server responds with JSON (JavaScript Object Notation), which is lightweight, language-independent, and easy for client applications to parse.

Endpoints

Here are the API endpoints we will build:

Method	Endpoint	Description
GET	/countries_api/get_all	List all countries
GET	/countries_api/get_one/{id}	Get a single country
POST	/countries_api/create	Create a new country
PUT	/countries_api/update/{id}	Update an existing country
DELETE	/countries_api/destroy/{id}	Delete a country

How This Differs From The CRUD Chapter

The admin CRUD module we built earlier used HTML views through the admin template. Every method returned a full page with forms, tables, and navigation. The REST API, by contrast, returns only JSON data. There are no views, no templates, no forms - just raw data in a standardised format.

Authentication also differs. The admin CRUD module used the session-based gatekeeper pattern: if you had a valid admin session, you could access the page. The REST API uses token-based authentication, where each request includes an API token in the HTTP headers. This allows non-browser clients - mobile apps, third-party services, automated scripts - to authenticate without maintaining a session.

Trongate provides the tools for token authentication, but it is entirely up to you to decide which endpoints require authentication and what the access rules should be. You may choose to expose certain endpoints publicly (a read-only list of countries, for example), require a token for write operations only, or lock down every endpoint. The framework gives you the means; you set the policy.

For a full understanding of how tokens work, see Understanding Trongate's Token System in the framework documentation.

What You Will Learn

• Building a Trongate controller that returns JSON
• Token-based authentication for API requests
• Reading and parsing JSON request bodies
• Setting appropriate HTTP response status codes
• Validating input and returning structured error messages
• Using before and after hooks for cross-cutting concerns

Let us begin by setting up a new module: countries_api.