SilverStripe\RestfulServer\RestfulServer
Generic RESTful server, which handles webservice access to arbitrary DataObjects.
Relies on serialization/deserialization into different formats provided
by the DataFormatter APIs in core.
Synopsis
class RestfulServer
extends Controller
{
- // members
- private static array $url_handlers = ;
- private static string $api_base = "api/v1/";
- private static string $authenticator = BasicRestfulAuthenticator::class;
- private static string $default_extension = "xml";
- private static array $endpoint_aliases = ;
- private static boolean $location_header_on_create = true;
- protected static string $default_mimetype = "text/xml";
- protected Member $member;
- private static array $allowed_actions = ;
- // methods
- public void init()
- protected string sanitiseClassName()
- protected string unsanitiseClassName()
- public static string|array parseRelationClass()
- public void index()
- protected string getHandler()
- protected SS_List getSearchQuery()
- protected DataFormatter getDataFormatter()
- protected DataFormatter getRequestDataFormatter()
- protected DataFormatter getResponseDataFormatter()
- protected void deleteHandler()
- protected void putHandler()
- protected void postHandler()
- protected DataObject|string updateDataObject()
- protected DataList getObjectQuery()
- protected SQLQuery getObjectsQuery()
- protected SQLQuery|boolean getObjectRelationQuery()
- protected string permissionFailure()
- protected string notFound()
- protected string methodNotAllowed()
- protected string unsupportedMediaType()
- protected mixed validationFailure()
- protected string exceptionThrown()
- protected Member|false authenticate()
- protected array getAllowedRelations()
- protected Member|null getMember()
- protected string resolveClassName()
Hierarchy
Extends
- SilverStripe\Control\Controller
Tasks
Line | Task |
---|---|
43+ | Implement PUT/POST/DELETE for relations |
43+ | Access-Control for relations (you might be allowed to view Members and Groups, but not their relation with each other) |
43+ | Make SearchContext specification customizeable for each class |
43+ | Allow for range-searches (e.g. on Created column) |
43+ | Filter relation listings by $api_access and canView() permissions |
43+ | Exclude relations when "fields" are specified through URL (they should be explicitly requested in this case) |
43+ | Custom filters per DataObject subclass, e.g. to disallow showing unpublished pages in SiteTree/Versioned/Hierarchy |
43+ | URL parameter namespacing for search-fields, limit, fields, add_fields (might all be valid dataobject properties) e.g. you wouldn't be able to search for a "limit" property on your subclass as its overlayed with the search logic |
43+ | i18n integration (e.g. Page/1.xml?lang=de_DE) |
43+ | Access to extendable methods/relations like SiteTree/1/Versions or SiteTree/1/Version/22 |
43+ | Respect $api_access array notation in search contexts |
122 | In 3.2 we should make the default Live, then change to Stage in the admin area (with a nicer API) |
272+ | Access checking |
367+ | Allow specifying of different searchcontext getters on model-by-model basis |
559+ | Posting to an existing URL (without a relation) current resolves in creatig a new element, rather than a "Conflict" message. |
677 | Disallow editing of certain keys in database |
871+ | Respect field level permissions once they are available in core |
Members
private
- $allowed_actions
- $api_base — string
- $authenticator — string
- $default_extension
—
string
If no extension is given in the request, resolve to this extension (and subsequently the {@link self::$default_mimetype}. -
$endpoint_aliases
Custom endpoints that map to a specific class. - $location_header_on_create
—
boolean
Whether or not to send an additional "Location" header for POST requests to satisfy HTTP 1.1: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html - $url_handlers — array
protected
- $default_mimetype
—
string
If no extension is given, resolve the request to this mimetype. - $member — SilverStripe\Security\Member
Methods
protected
- authenticate() — A function to authenticate a user
- deleteHandler() — Handler for object delete
- exceptionThrown()
- getAllowedRelations() — Return only relations which have $api_access enabled.
- getDataFormatter() — Returns a dataformatter instance based on the request extension or mimetype. Falls back to {@link self::$default_extension}.
- getHandler() — Handler for object read.
- getMember() — Get the current Member, if available
- getObjectQuery() — Gets a single DataObject by ID, through a request like /api/v1/<MyClass>/<MyID>
- getObjectRelationQuery()
- getObjectsQuery()
- getRequestDataFormatter()
- getResponseDataFormatter()
- getSearchQuery() — Uses the default {@link SearchContext} specified through {@link DataObject::getDefaultSearchContext()} to augument an existing query object (mostly a component query from {@link DataObject}) with search clauses.
- methodNotAllowed()
- notFound()
- permissionFailure()
- postHandler() — Handler for object append / method call.
- putHandler() — Handler for object write
- resolveClassName() — Checks if given param ClassName maps to an object in endpoint_aliases, else simply return the unsanitised version of ClassName
- sanitiseClassName() — Backslashes in fully qualified class names (e.g. NameSpaced\ClassName) kills both requests (i.e. URIs) and XML (invalid character in a tag name) So we'll replace them with a hyphen (-), as it's also unambiguious in both cases (invalid in a php class name, and safe in an xml tag name)
- unsanitiseClassName() — Convert hyphen escaped class names back into fully qualified PHP safe variant.
- unsupportedMediaType()
- updateDataObject() — Converts either the given HTTP Body into an array (based on the DataFormatter instance), or returns the POST variables.
- validationFailure()
public
- index() — This handler acts as the switchboard for the controller.
- init()
- parseRelationClass() — Parse many many relation class (works with through array syntax)