usox / json-schema-api
Json schema powered api creation for php
Fund package maintenance!
usox
Installs: 21 089
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ~8.3
- ext-json: *
- opis/json-schema: ^2.1
- php-http/discovery: ^1.13
- psr/http-factory: ^1.0
- psr/http-message: ^1||^2
- psr/http-server-handler: ^1.0
- psr/log: ^1.1||^3
- ramsey/uuid: ^4.1
- teapot/status-code: ^2
Requires (Dev)
README
JsonSchemaApi
This library provides a simple way to create a json api using json-schema to validate the request. You can leverage most of the input validation tasks (variables types, length/content-constraints, lists containing just certain items, etc.) to the json schema validator and work with the data right away.
Json-Schema
Every method needs a corresponding schema-file which describes, how the request data should look alike.
You can find a simple example in the example/schema
-folder.
Every request has also to follow a basic schema (see dist/request.json
) which contains informations about the method.
Validation
Every request and the generated response will be validated against the provided schema.
Requirements
This library requires existing psr7 and psr17 implementations.
Install
composer require usox/json-schema-api
Usage
Just use the factory method to create the endpoint. The factory automatically searches for a existing psr17 stream factory implementation, but you can also provide a factory instance when calling the method.
Get your method-provider ready (see below) and call the factory
-method on the endpoint to retrieve a working instance:
The serve method requires a psr request and returns a psr response.
$endpoint = \Usox\JsonSchemaApi\Endpoint::factory( $methodProvider ); $endpoint->serve( $psr7Request, $psr7Response );
Optional: PSR15 Middleware
The endpoint class implements the PSR15 RequestHandlerInterface
.
MethodProvider
The MethodProvider
is the source for your api methods - this could be a simple array, a DI-Container, etc. The class has to implement Usox\JsonSchemApi\Contract\MethodProviderInterface
.
class MyMethodProvider implements \Usox\JsonSchemaApi\Contract\MethodProviderInterface { private array $methodList = ['beerlist' => BeerlistMethod::class]; public function lookup(string $methodName) : ?\Usox\JsonSchemaApi\Contract\ApiMethodInterface { $handler = $this->methodList[$methodName] ?? null; if ($handler === null) { return null; } return new $handler; } }
API-Method
The lookup
-method in the MethodProvider must return an instance of Usox\JsonSchemaApi\Contract\ApiMethodInterface
.
Every api method handler must define at least those two methods:
- The
handle
method which processes the request and returns the result - The
getSchemaFile
method which returns the path to the schema file which is used to validate the request
class BeerlistMethod implements \Usox\JsonSchemaApi\Contract\ApiMethodInterface { public function handle(stdClass $parameter) : array { return ['ipa', 'lager', 'weizen']; } public function getSchemaFile() : string { return '/path/to/schema.json'; } }
Example
You can find a working example in the example
-folder.
Just cd to the example-folder and fire up the the php internal webserver php -S localhost:8888
.
Now you can send POST
-Requests to the api like this using curl.
curl -X POST -d '{"method": "beerlist", "parameter": {"test1": "foobar", "test2": 666}}' "http://localhost:8888"
Error-Handling
Basically there are three types of errors. All of them get logged.
ApiExceptions
If a handler throws an exception which extends the ApiException
exception class, the api will
return a Bad Request (400)
response including an error message (the exception message) and an error code for reference
within a json response.
InternalException
Internal errors, like non-existing schema files, invalid schemas and such, will return a Internal Server Error (500)
response and create a log entry (if a logger is provided).
In addition, optionally available context information within the exception will be logged, too.
Throwable
Any Throwable which are thrown within an api handler, will be catched, logged and return a Internal Server Error (500)
response.