Grav API Plugin
The API Plugin for Grav adds a REST API to Grav.
| IMPORTANT!!! This plugin is currently in development as is to be considered an alpha release. As such, use this in a production environment at your own risk!. More features will be added in the future.
Installation
Or clone from GitHub and put in the user/plugins/api
folder.
Principles
- Two URLs per resource: one for the resource collection, one for the individual resource
- Use plural forms
- Keep URLs as short as possible
- Use nouns as resource names
HTTP Method Names
- GET: read a resource or collection
- POST: create a resource
- PUT: update a resource
- DELETE: remove a resource
HTTP Status Codes
Use meaningful HTTP Status Codes (TODO)
- 200: Success.
- 201: Created. Returned on successful creation of a new resource. Include a 'Location' header with a link to the newly-created resource.
- 400: Bad request. Data issues such as invalid JSON, etc.
- 403: Forbidden. Example: trying to create a page already existing
- 404: Not found. Resource not found on GET.
- 405: Not Allowed.
- 501: Not Implemented. Returned by default by non implemented API methods
Things still missing
- Support filtering, sorting and pagination on collections
- Allow clients to reduce the number of fields that come back in the response
- Access control to each API method, for groups or single users
- Use http://fractal.thephpleague.com
- Allow plugins to add API methods
- Allow to limit access to a specific IP (range)
- Use OAuth2 to secure the API http://oauth2.thephpleague.com/
- JSONP
- Return the children of a page in the page request, if desired
- Allow to only retrieve some fields on API calls that are heavy on the system (e.g.
GET /api/pages/:page
)
Authentication
In this current form the Grav API uses Basic Authentication, with the username and password currently set in Grav. It's just a first implementation, willing to change that at least with digest authentication.
Users with admin.super
or admin.api
permissions can access the whole API.
Usage or Basic Authentication on the client-side
On the client side, add the authorization header of the request as follows:
Authorization: Basic <Base64 encoded value>
the base64 value is username:password
Standard Grav API Endpoints
Implemented
Version
Methods that return the API plugin version. Depending on the returned value, some methods might be available or not depending on the plugin evolution. To be used by clients when interacting with the Grav API.
GET /api/version
Get the API plugin major version.
e.g. "0" or "1"
GET /api/version/major
Same as GET /api/version
e.g. "0" or "1"
GET /api/version/minor
Get the API plugin major and minor version.
e.g. "0.1" or "1.0"
GET /api/version/full
Get the API plugin full version.
e.g. "0.1.3"
Pages
GET /api/pages
Lists the site pages
GET /api/pages/:page
Get a specific page
e.g. /api/pages/blog/my-first-post e.g. /api/pages/contact
Users
GET /api/users
Lists the site users
GET /api/users/:user
Get a specific user
e.g. /api/users/admin e.g. /api/users/andy
Not yet implemented
- GET /api/plugins
- GET /api/plugins/shoppingcart
- GET /api/themes
- GET /api/themes/theme
- GET /api/data
- GET /api/logs
- GET /api/config
- GET /api/config/system
- GET /api/config/plugin/:pluginName
- GET /api/backups
- GET /api/gpm
- POST /api/gpm/update
- GET /api/grav
- POST /api/grav/self-upgrade
- GET /api/version
- GET /api/debug
- .....