Download the PHP package pstaender/silverstripe-restful-api without Composer

Restul API for SilverStripe

This module provides an basic API controller with helpers to manage (underscore based) JSON data for i/o. Additionally there are some helpful methods on DataObjects, forApi() for instance. To authenticate the API controller is using the SilverStripe build security system but provides an Auth controller to authenticate in a restful way.

Motivation

Build fast and easy API's without writing the same helper methods over and over again. Currently it's in a development state, so some (design) decision might change to provide the convenient tools with at least surprising behaviour.

Configuration

The following attributes can be configured:

To avoid unnecessary authentication during development you can use the adminAccessToken (default is 84c44b7ee63a9919aa272673eecfc7f9b7424e47 in dev mode).

How to use

Authentication

Login

POST:http://localhost/auth/session with (json) body:

Returns (with StatusCode 200):

Now you can use the accesstoken to perform actions.

Session info

GET:http://localhost/auth/session with header X-Accesstoken: 8d69f3f127a9ddc4f73d75c5803c846696bb10ff (you always have to attach the Accesstoken this way to get authenticated!) returns (with StatusCode 200):

Logout (delete Session)

DELETE:http://localhost/auth/session/8d69f3f127a9ddc4f73d75c5803c846696bb10ff with header X-Accesstoken: 8d69f3f127a9ddc4f73d75c5803c846696bb10ff returns (with StatusCode 202):

Use in your project

You can also (check out this more detailed example)[https://github.com/pstaender/silverstripe-restful-api/blob/master/code/examples/Country.php].

Data model(s)

You may apply some extra definitions on your models to prepare them for API use:

Controller for Schema Definition

To provide a suitable schema definition of your models you can explicit allow them in your config.yml via:

So that schema/Member will display s.th. like:

API Controller(s)

How to define your own API Controller including some methods (we assume that you've added s.th. like "client//$Action/$ID": "ClientController" to your routes.yml):

Interesting Controller helpers:

• getAccessTokenFromRequest
  • Returns the accesstoken from the header
• getSessionFromRequest
  • The session DataObject (if existing)
• sendData($data = null, $code = null)
  • Send a DataList, DataObject or an Array; will be rendered as JSON by default
• sendJSON($data = null, $code = null)
  • Same as sendData, except to force JSON
• sendError($errMsg, $code = 500)
  • Use to send comprehensible error messages for the API user
• sendNotFound($msg = 'resource not found', $code = 404)
  • Helper to send a default "Resource not found" error message
• sendSuccessfulDelete($msg = 'resource deleted successfully', $code = 202)
  • Helper to send a default "Resource deleted successfully" message after a DELETE
• sendSuccessfulPut($msg = 'resource updated successfully', $code = 202)
  • Helper to send a default "Resource updated successfully" message after a PUT
• sendSuccessfulPost($uriOrData = null, $msg = 'resource created succesfully', $code = 201)
  • Helper to redirect to new resource (if $uriOrData is a string) or send a default "Resource created successfully" message after a POST

To keep it simple: the arguments order of $msg and $code is arbitrary.

Tests

or

to run specific tests.

Ensure that you have defined $_FILE_TO_URL_MAPPING in _ss_environment.php to run controller tests correctly (otherwise redirects will throw an user error for instance).

Better performance

By deactivating blocking sessions, you can decrease the response time.

Beware that none across request session will work anymore on your SilverStripe project because persistent session storage is deactivated in that scenario (not needed in pure restful services anyway).

To activate this feature, add to your _config.php or _ss_environment.php:

Licence

MIT License