dev-master
9999999-dev https://github.com/govtnz/silverstripe-api.gitA facade pattern API implementation for Silverstripe using interfaces and Swagger
MIT License
The Requires
by Govt.nz
api php silverstripe interface facade pattern
A facade pattern API implementation for Silverstripe using interfaces and Swagger
A facade pattern API implementation for SilverStripe using interfaces and optionally Swagger., (*1)
This is an opinionated package that implements a SilverStripe API with the following features:, (*3)
You can structure your API in whatever way makes the most logical sense to its consumers: this is the facade pattern., (*4)
In many cases the class implementing an interface could be an existing Page Controller, but you're entirely free to have a separate class purely for implementing the API interface., (*5)
This package is being developed progressively by the Govt.nz team, and features are being added as they're required for our own project., (*6)
This means that some desirable features have not yet been implemented., (*7)
OAuth and permissions checking, for example, will only be added when we need them ourselves., (*8)
composer require govtnz/silverstripe-api
The /resources/data_dir subdirectory within this module contains interface samples., (*9)
Use Swagger-UI or manually browse the assets/api/v1/swagger.json file to learn the other available API requests., (*10)
GovtNZ\SilverStripe\Api\ApiManager: api: v1: definition: 'path/to/base.txt' interfaces: - ApiInterfaceOne stubs - ApiInterfaceStubOne v2: definition: 'path/to/base.txt' interfaces: - ApiInterfaceOne stubs - ApiInterfaceStubOne
silverstripe-api allows you to break your API definition into blocks distributed across multiple files., (*11)
It's not mandatory to split up your API definition: if you wish, you can write it as a single block. But splitting it up improves maintainability, and the dev task API: Rebuild definitions will still generate a single swagger.json file for each API version., (*12)
However you structure your API definition, it needs to be, (*13)
contained in mulit-line comment blocks:, (*14)
/* (json here) */
Unlike a regular JSON file, you can include // comments in your API definitions (but don't use /* */ comments). These // comments will be ignored by the dev task that generates the swagger.json output. The dev task will assume that each chunk of JSON is a top-level element within the Swagger definition: the provided examples demonstrate this., (*15)
The dev task API: Rebuild definitions takes the JSON fragments from each interface and builds them into a single swagger.json file., (*16)
By default the resulting swagger.json file is saved in /assets/api, but you can change that with a .yml config setting:, (*17)
Swagger: data-dir: [PATH]
And if you're integrating govtnz/swagger-ui with this API module, this path must be externally accessible., (*18)
Each API directory must have a file which defines properties that are common across all the interface nodes., (*19)
There are two useful variables available within this text file which can make your API definitions more portable between dev, test and production servers:, (*20)
You can use getHost to automatically populate the "host" key:, (*21)
"host": "<% getHost %>",
You can use getProtocol to automatically populate the "schemes" array:, (*22)
"schemes": [ "<% getProtocol %>" ],
It's recommended that you copy and modify the existing resources/base.txt file to kick-start your own API development., (*23)
Automated tests can be written to exercise each interface and its stub file. These can be stored in the /tests subdirectory., (*24)
Each file in the stubs directory implements an API interface using static data. It is invoked in one of two circumstances:, (*25)
&test=true
.Stub files are not mandatory, but they're useful for testing as their responses never change., (*26)
There are several useful functions in the ApiController
:, (*27)
Your implementation code can:, (*28)
Your implementation must:, (*29)
For example, the API method organisation/sector returns a list of organisation sectors, not a list of organisations. In this instance set pronoun to sector so the output is appropriately described., (*30)
There is a companion package, govtnz/swagger-ui, which forks Swagger UI and makes it easy to include in a SilverSripe project., (*31)
See the documentation within this companion Swagger package for more details., (*32)
A facade pattern API implementation for Silverstripe using interfaces and Swagger
MIT License
api php silverstripe interface facade pattern