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-api
cd scaffold-api
neoan3 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!
