{"id":18770426,"url":"https://github.com/colymba/silverstripe-restfulapi","last_synced_at":"2025-09-12T00:10:56.090Z","repository":{"id":56956705,"uuid":"11265072","full_name":"colymba/silverstripe-restfulapi","owner":"colymba","description":"SilverStripe RESTful API with a default JSON serializer.","archived":false,"fork":false,"pushed_at":"2024-01-15T13:17:06.000Z","size":450,"stargazers_count":64,"open_issues_count":36,"forks_count":35,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-31T07:06:09.091Z","etag":null,"topics":["api","restful","restfull-api","silverstripe"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/colymba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-07-08T20:48:52.000Z","updated_at":"2024-03-20T08:20:54.000Z","dependencies_parsed_at":"2024-06-19T06:12:34.218Z","dependency_job_id":"0e389779-dbdf-4e29-b679-5ca77358cd18","html_url":"https://github.com/colymba/silverstripe-restfulapi","commit_stats":{"total_commits":165,"total_committers":12,"mean_commits":13.75,"dds":"0.10303030303030303","last_synced_commit":"5d9a866da0de08dacd96242d3364926fd637b8df"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colymba%2Fsilverstripe-restfulapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colymba%2Fsilverstripe-restfulapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colymba%2Fsilverstripe-restfulapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/colymba%2Fsilverstripe-restfulapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/colymba","download_url":"https://codeload.github.com/colymba/silverstripe-restfulapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","restful","restfull-api","silverstripe"],"created_at":"2024-11-07T19:19:30.390Z","updated_at":"2025-04-07T09:19:05.342Z","avatar_url":"https://github.com/colymba.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":":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:\n\n# SilverStripe RESTful API\n\n[![Build Status](https://travis-ci.org/colymba/silverstripe-restfulapi.png?branch=master)](https://travis-ci.org/colymba/silverstripe-restfulapi)\n\nThis 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.\n\n\n## API URL structure\n\n| Action                | HTTP Verb | URL                                     |\n| :-------------------- | :-------- | :-------------------------------------- |\n| Find 1 record         | `GET`     | `api/Model/ID`                          |\n| Find multiple records | `GET`     | `api/Model?param=val\u0026__rand=1234`       |\n| Update a record       | `PUT`     | `api/Model/ID`                          |\n| Create a record       | `POST`    | `api/Model`                             |\n| Delete a record       | `DELETE`  | `api/Model/ID`                          |\n| -                     | -         | -                                       |\n| Login \u0026 get token     | n/a       | `api/auth/login?email=***\u0026pwd=***`      |\n| Logout                | n/a       | `api/auth/logout`                       |\n| Password reset email  | n/a       | `api/auth/lostPassword?email=***`       |\n| -                     | -         | -                                       |\n| Custom ACL methods    | n/a       | `api/acl/YOURMETHOD`                    |\n\n`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:\n* `api/Book/33`\n* `api/Book?title=Henry`\n* `api/Book?title__StartsWith=Henry`\n* `api/Book?title__StartsWith=Henry\u0026__rand=123456\u0026__limit=1`\n* `api/Book?title__StartsWith=Henry\u0026__rand=123456\u0026__limit[]=10\u0026__limit[]=5`\n\nThe allowed `/auth/$Action` must be defined on the used `Authenticator` class via the `$allowed_actions` config.\n\n\n## Requirements\n* [SilverStripe Framework 4+](https://github.com/silverstripe/silverstripe-framework)\n\n\n## Quick features highlight\n* [Configurable components](#components)\n* [CORS enabled](doc/RESTfulAPI.md#cors)\n* [Embedded records](doc/RESTfulAPI.md#embedded-records)\n* [Sideloaded records (EmberDataSerializer)](doc/EmberDataSerializer.md#sideloaded-records)\n* [Authentication](doc/TokenAuthenticator.md)\n* [DataObject \u0026 Config level api access control](doc/RESTfulAPI.md#authentication-and-api-access-control)\n* [Search filter modifiers](doc/DefaultQueryHandler.md#search-filter-modifiers)\n\n\n## What's all this?\n### RESTfulAPI\nThis 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 \u0026 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.\n\nIf CORS are enabled (true by default), the right headers are taken care of too.\n\n\n### Components\nThe `RESTfulAPI` uses 4 types of components, each implementing a different interface:\n* Authetication (`Authenticator`)\n* Permission Management (`PermissionManager`)\n* Query Handler (`QueryHandler`)\n* Serializer (`Serializer`)\n\n\n### Default components\nThis API comes with defaults for each of those components:\n* `TokenAuthenticator` handles authentication via a token in an HTTP header or variable\n* `DefaultPermissionManager` handles DataObject permission checks depending on the HTTP request\n* `DefaultQueryHandler` handles all find, edit, create or delete for models\n* `DefaultSerializer` / `DefaultDeSerializer` serialize query results into JSON and deserialize client payloads\n* `EmberDataSerializer` / `EmberDataDeSerializer` same as the `Default` version but with specific fomatting fo Ember Data.\n\nYou 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`.\n\n\n### Token Authentication Extension\nWhen using `TokenAuthenticator` you must add the `TokenAuthExtension` `DataExtension` to a `DataObject` and setup `TokenAuthenticator` with the right config.\n\n**By default, API authentication is disabled.**\n\n\n### Permissions management\nDataObject API access control can be managed in 2 ways. Through the `api_access` [YML config](doc/RESTfulAPI.md#authentication-and-api-access-control) allowing for simple configurations, or via [DataObject permissions](http://doc.silverstripe.org/framework/en/reference/dataobject#permissions) through a `PermissionManager` component.\n\nA sample `Group` extension `GroupExtension` is also available with a basic set of dedicated API permissions. This can be enabled via [config](code/_config/config.yml#L11) or you can create your own.\n\n**By default, the API only performs access control against the `api_access` YML config.**\n\n\n### Config\nSee individual component configuration file for mode details\n* [RESTfulAPI](doc/RESTfulAPI.md) the root of the api\n* [TokenAuthenticator](doc/TokenAuthenticator.md) handles query authentication via token\n* [DefaultPermissionManager](doc/DefaultPermissionManager.md) handles DataObject level permissions check\n* [DefaultQueryHandler](doc/DefaultQueryHandler.md) where most of the logic happens\n* [DefaultSerializer](doc/DefaultSerializer.md) DefaultSerializer and DeSerializer for everyday use\n* [EmberDataSerializer](doc/EmberDataSerializer.md) EmberDataSerializer and DeSerializer speicifrcally design for use with Ember Data and application/vnd.api+json\n\nHere is what a site's `config.yml` file could look like:\n```yaml\n---\nName: mysite\nAfter:\n    - 'framework/*'\n    - 'cms/*'\n---\n# API access\nArtwork:\n  api_access: true\nAuthor:\n  api_access: true\nCategory:\n  api_access: true\nMagazine:\n  api_access: true\nTag:\n  api_access: 'GET,POST'\nVisual:\n  api_access: true\nImage:\n  api_access: true\nFile:\n  api_access: true\nPage:\n  api_access: false\n# RestfulAPI config\nColymba\\RESTfulAPI\\RESTfulAPI:\n  authentication_policy: true\n  access_control_policy: 'ACL_CHECK_CONFIG_AND_MODEL'\n  dependencies:\n    authenticator: '%$Colymba\\RESTfulAPI\\Authenticators\\TokenAuthenticator'\n    authority: '%$Colymba\\RESTfulAPI\\PermissionManagers\\DefaultPermissionManager'\n    queryHandler: '%$Colymba\\RESTfulAPI\\QueryHandlers\\DefaultQueryHandler'\n    serializer: '%$Colymba\\RESTfulAPI\\Serializers\\EmberData\\EmberDataSerializer'\n  cors:\n    Enabled: true\n    Allow-Origin: 'http://mydomain.com'\n    Allow-Headers: '*'\n    Allow-Methods: 'OPTIONS, GET'\n    Max-Age: 86400\n# Components config\nColymba\\RESTfulAPI\\QueryHandlers\\DefaultQueryHandler\\DefaultQueryHandler:\n  dependencies:\n    deSerializer: '%$Colymba\\RESTfulAPI\\Serializers\\EmberData\\EmberDataDeSerializer'\nColymba\\RESTfulAPI\\Serializers\\EmberData\\EmberDataSerializer:\n  sideloaded_records:\n    Artwork:\n      - 'Visuals'\n      - 'Authors'\n```\n\n\n## Todo\n* API access IP throttling (limit request per minute for each IP or token)\n* Check components interface implementation\n\n\n## License \n[BSD 3-clause license](LICENSE)\n\nCopyright (c) 2018, Thierry Francois (colymba)\nAll rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolymba%2Fsilverstripe-restfulapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolymba%2Fsilverstripe-restfulapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolymba%2Fsilverstripe-restfulapi/lists"}