2017 © Pedro Peláez
 

silverstripe-module silverstripe-restfulapi

SilverStripe 3 RESTful API with a default JSON serializer.

image

colymba/silverstripe-restfulapi

SilverStripe 3 RESTful API with a default JSON serializer.

  • Thursday, January 4, 2018
  • by colymba
  • Repository
  • 12 Watchers
  • 61 Stars
  • 11,880 Installations
  • PHP
  • 1 Dependents
  • 0 Suggesters
  • 29 Forks
  • 29 Open issues
  • 8 Versions
  • 4 % Grown

The README.md

:warning: I haven't been able to give as much love as I would like to these repos as they deserve. If you have time and are interested to help maintain them, give me a shout. :rotating_light:, (*1)

SilverStripe RESTful API

Build Status, (*2)

This module implements a RESTful API for read/write access to your SilverStripe Models. It comes bundled with a default Token Authenticator, Query Handler and JSON Serializers, and can be extended to your need and to return XML or other content type via custom components., (*3)

API URL structure

Action HTTP Verb URL
:-------------------- :-------- :--------------------------------------
Find 1 record GET api/Model/ID
Find multiple records GET api/Model?param=val&__rand=1234
Update a record PUT api/Model/ID
Create a record POST api/Model
Delete a record DELETE api/Model/ID
- - -
Login & get token n/a api/auth/login?email=***&pwd=***
Logout n/a api/auth/logout
Password reset email n/a api/auth/lostPassword?email=***
Custom ACL methods n/a api/acl/YOURMETHOD

Model being the class name of the model you are querying (name formatting may vary depending on DeSerializer used). For example with a model class named Book URLs would look like: * api/Book/33 * api/Book?title=Henry * api/Book?title__StartsWith=Henry * api/Book?title__StartsWith=Henry&__rand=123456&__limit=1 * api/Book?title__StartsWith=Henry&__rand=123456&__limit[]=10&__limit[]=5, (*4)

The allowed /auth/$Action must be defined on the used Authenticator class via the $allowed_actions config., (*5)

Requirements

Quick features highlight

What's all this?

RESTfulAPI

This is the main API Controller that receives all the requests, checks if authentication is needed and passing control to the authenticator if true, the resquest is then passed on to the QueryHandler, which uses the DeSerializer to figure out model & column names and decode the eventual payload from the client, the query result is then passed to the Serializer to be formatted and then returned to the client., (*6)

If CORS are enabled (true by default), the right headers are taken care of too., (*7)

Components

The RESTfulAPI uses 4 types of components, each implementing a different interface: * Authetication (Authenticator) * Permission Management (PermissionManager) * Query Handler (QueryHandler) * Serializer (Serializer), (*8)

Default components

This API comes with defaults for each of those components: * TokenAuthenticator handles authentication via a token in an HTTP header or variable * DefaultPermissionManager handles DataObject permission checks depending on the HTTP request * DefaultQueryHandler handles all find, edit, create or delete for models * DefaultSerializer / DefaultDeSerializer serialize query results into JSON and deserialize client payloads * EmberDataSerializer / EmberDataDeSerializer same as the Default version but with specific fomatting fo Ember Data., (*9)

You can create you own classes by implementing the right interface or extending the existing components. When creating you own components, any error should be return as a RESTfulAPIError object to the RESTfulAPI., (*10)

Token Authentication Extension

When using TokenAuthenticator you must add the TokenAuthExtension DataExtension to a DataObject and setup TokenAuthenticator with the right config., (*11)

By default, API authentication is disabled., (*12)

Permissions management

DataObject API access control can be managed in 2 ways. Through the api_access YML config allowing for simple configurations, or via DataObject permissions through a PermissionManager component., (*13)

A sample Group extension GroupExtension is also available with a basic set of dedicated API permissions. This can be enabled via config or you can create your own., (*14)

By default, the API only performs access control against the api_access YML config., (*15)

Config

See individual component configuration file for mode details * RESTfulAPI the root of the api * TokenAuthenticator handles query authentication via token * DefaultPermissionManager handles DataObject level permissions check * DefaultQueryHandler where most of the logic happens * DefaultSerializer DefaultSerializer and DeSerializer for everyday use * EmberDataSerializer EmberDataSerializer and DeSerializer speicifrcally design for use with Ember Data and application/vnd.api+json, (*16)

Here is what a site's config.yml file could look like:, (*17)

---
Name: mysite
After:
    - 'framework/*'
    - 'cms/*'
---
# API access
Artwork:
  api_access: true
Author:
  api_access: true
Category:
  api_access: true
Magazine:
  api_access: true
Tag:
  api_access: 'GET,POST'
Visual:
  api_access: true
Image:
  api_access: true
File:
  api_access: true
Page:
  api_access: false
# RestfulAPI config
Colymba\RESTfulAPI\RESTfulAPI:
  authentication_policy: true
  access_control_policy: 'ACL_CHECK_CONFIG_AND_MODEL'
  dependencies:
    authenticator: '%$Colymba\RESTfulAPI\Authenticators\TokenAuthenticator'
    authority: '%$Colymba\RESTfulAPI\PermissionManagers\DefaultPermissionManager'
    queryHandler: '%$Colymba\RESTfulAPI\QueryHandlers\DefaultQueryHandler'
    serializer: '%$Colymba\RESTfulAPI\Serializers\EmberData\EmberDataSerializer'
  cors:
    Enabled: true
    Allow-Origin: 'http://mydomain.com'
    Allow-Headers: '*'
    Allow-Methods: 'OPTIONS, GET'
    Max-Age: 86400
# Components config
Colymba\RESTfulAPI\QueryHandlers\DefaultQueryHandler\DefaultQueryHandler:
  dependencies:
    deSerializer: '%$Colymba\RESTfulAPI\Serializers\EmberData\EmberDataDeSerializer'
Colymba\RESTfulAPI\Serializers\EmberData\EmberDataSerializer:
  sideloaded_records:
    Artwork:
      - 'Visuals'
      - 'Authors'

Todo

  • API access IP throttling (limit request per minute for each IP or token)
  • Check components interface implementation

License

BSD 3-clause license, (*18)

Copyright (c) 2018, Thierry Francois (colymba) All rights reserved., (*19)

The Versions

04/01 2018

dev-master

9999999-dev https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

12/06 2017

v2.1.2

2.1.2.0 https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

14/03 2017

dev-travis

dev-travis https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

14/03 2017

v2.1.1

2.1.1.0 https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

29/06 2015

v2.1.0

2.1.0.0 https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

29/06 2015

dev-create-model-refactor

dev-create-model-refactor https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

30/06 2014

v2.0.0

2.0.0.0 https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server

19/06 2014

v1.0.0

1.0.0.0 https://github.com/colymba/silverstripe-model-serializer

SilverStripe 3 RESTful API with a default JSON serializer.

  Sources   Download

BSD Simplified

The Requires

 

api rest api rest restful silverstripe json api model serializer rest server restful server