Scaffolding REST APIs with JWT authentication

repo

Scaffolding an API?

While walking students through a neoan3 tutorial the other day, I noticed a demo I built could actually be used to scaffold an API for all kind of use-cases. The result of what I built went far beyond the original plan: to create a simple backend for testing and developing. Through to the architecture of this creator tool, one can use it to quickly set up a simple API and later built it out to be a scalable and robust production solution. That's right! A cli-based generator of API endpoints that scaffolds a solid backend for you.

First, let's have a look at setting it up.

Prerequisites

All you need is a local PHP installation (7.4), composer and neoan3-cli (make sure you install it globally and that it is available in your path)

Installation

composer create-project sroehrl/scaffold-apicd scaffold-apineoan3 develop

At this point you should see that the server started on localhost:8080. All endpoints are exposed at localhost:8080/api.v1/

What now?

The app already ships with authentication based on JWT, so we can use our existing app (or postman?) to register a user:

POST /api.v1/users

You can make changes to the register & login behavior by going to "/models/users/users.model.php", but by default, the model expects at least

• userName and
• password

as fields. You can add whatever else you want to store to the user. Once created, the API will respond with a status code of 200, as well as your user-object and a JWT token.

NOTE: per default, all custom endpoints require a valid baerer token. So unless you fire at the login (POST /api.v1/users/auth) or the registration (POST /api.v1/users), you will need to use this token as authorization header (look at the javascript examples in the readme).

Custom endpoints

Now the interesting part: Authentication is the starting point, but what then? A simple command creates additional endpoints:

php scaffold tags for example, will generate the following files:

/component/tags/tags.ctrl.php and /model/tags/tag.model.php

Their content will make the following endpoints available:

POST /api.v1/tags creates new tag

PUT /api.v1/tags/:tag-id updates a tag

GET /api.v1/tags lists/searches for tags (get-parameters with conditions can be used)

GET /api.v1/tags/:tag-id retrieves specific tag by id.

Want to make your endpoint public for now? Simply comment out Stateless::restrict() in component/tags/tags.ctrl.php in the appropriate method function.

So far so good. Now simply send a POST call with a json-payload to /api.v1/tags and you have your first tag.

Let me know what you think!