A facade pattern API implementation for SilverStripe using interfaces and Swagger
A facade pattern API implementation for SilverStripe using interfaces and optionally Swagger.
This is an opinionated package that implements a SilverStripe API with the
You can structure your API in whatever way makes the most logical sense to its
consumers: this is the facade pattern.
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.
This package is being developed progressively by the Govt.nz team, and features
are being added as they're required for our own project.
This means that some desirable features have not yet been implemented.
OAuth and permissions checking, for example, will only be added when we need
composer require govtnz/silverstripe-api
The /resources/data_dir subdirectory within this module contains interface samples.
Use Swagger-UI or manually browse the assets/api/v1/swagger.json file to
learn the other available API requests.
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.
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.
However you structure your API definition, it needs to be
/* (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.
The dev task API: Rebuild definitions takes the JSON fragments from each
interface and builds them into a single swagger.json file.
By default the resulting swagger.json file is saved in /assets/api, but you
can change that with a .yml config setting:
Swagger: data-dir: [PATH]
And if you're integrating govtnz/swagger-ui with this API module, this path
must be externally accessible.
Each API directory must have a file which defines properties that are common
across all the interface nodes.
There are two useful variables available within this text file which can make
your API definitions more portable between dev, test and production servers:
You can use getHost to automatically populate the "host" key:
"host": "<% getHost %>",
You can use getProtocol to automatically populate the "schemes" array:
"schemes": [ "<% getProtocol %>" ],
It's recommended that you copy and modify the existing resources/base.txt
file to kick-start your own API development.
Automated tests can be written to exercise each interface and its stub file.
These can be stored in the /tests subdirectory.
Each file in the stubs directory implements an API interface using static
data. It is invoked in one of two circumstances:
Stub files are not mandatory, but they're useful for testing as their responses
There are several useful functions in the
Your implementation code can:
Your implementation must:
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.
There is a companion package, govtnz/swagger-ui,
which forks Swagger UI and makes it easy to include in a SilverSripe project.
See the documentation within this companion Swagger package for more details.
Module rating system helping users find modules that are well supported. For more on how the rating system works visit Module standards
Score not correct? Let us know there is a problem