heimrichhannot / contao-api-bundle
A generic API with restricted access to provide access to 3rd party applications.
Installs: 380
Dependents: 1
Suggesters: 0
Security: 0
Stars: 5
Watchers: 6
Forks: 12
Open Issues: 3
Type:contao-bundle
Requires
- php: ^7.4 || ^8.0
- contao/core-bundle: ^4.9
- firebase/php-jwt: ^4.0 || ^5.0
- heimrichhannot/contao-utils-bundle: ^2.214
- symfony/config: ^4.4 || ^5.0
- symfony/translation-contracts: ^1.0 || ^2.0 || ^3.0
Requires (Dev)
- contao/manager-plugin: ^2.0
- contao/test-case: 1.1
- friendsofphp/php-cs-fixer: ^2.2
- php-coveralls/php-coveralls: ^2.0
- php-http/guzzle6-adapter: ^1.1
- php-http/message-factory: ^1.0.2
- phpunit/phpunit: >=6.0 <6.5
- symfony/phpunit-bridge: ^3.2
Conflicts
- contao/manager-plugin: <2.0 || >=3.0
README
A generic API with restricted access to provide access to 3rd party applications.
Login /api/login/member
or api/login/user
Login is done via symfony guard
authenticator in combination with contao members tl_member
or users tl_user
.
After successful login a volatile token (default: 24 hours
) will be returned that is used for any api and must be provided within request headers Authorization: Bearer {{token}}
;
# test login (with contao front end member)
curl --user username:password -H "Content-Type: application/json" -X POST http://domain.tld/api/login/member
# example response on success
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmXtZSI6ImRpZ2l0YWxlc0BoZWltcmljaA1oYW5ub3QuZGUiLCJpYXQiOjE1MzY4NTYwMDMsImV4cCI6MTUzNjk0MjQwM30.trp-1NgYgXGfHYdE3dlQ8awE8aXUWL-RfBQyfWm2Hz0"
}
# test login (with contao back end member)
curl --user username:password -H "Content-Type: application/json" -X POST http://domain.tld/api/login/user
# example response on success
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmXtZSI6ImRpZ2l0YWxlc0BoZWltcmljaA1oYW5ub3QuZGUiLCJpYXQiOjE1MzY4NTYwMDMsImV4cCI6MTUzNjk0MjQwM30.trp-1NgYgXGfHYdE3dlQ8awE8aXUWL-RfBQyfWm2Hz0"
}
Create an app with an custom api key
Visit your contao backend at http://domain.tld/contao?do=api_apps
and create your first app.
Access can be restricted for member or user groups. Admin users tl_user
will have access to every api by default.
For each request beside the login routes you must provide the generated API key
as GET
Parameter.
Resource /api/resource/{resource_alias}
To add your custom resource, simply add an service within your bundles or app services.yml
:
services:
my.api.resource.my_resource:
class: MyApi\Resource\MyResource
arguments:
- "my_resource"
tags:
- { name: huh.api.resource, alias: my_resource}
And register your resource configuration within your bundles or app config.yml
:
huh:
api:
resources:
- {name: my_resource, type: entity_resource, modelClass: "MyResourceModel", verboseName: my_resource}
To get your config.yml
loaded properly, your Plugin
class must implement the interface Contao\ManagerPlugin\Config\ExtensionPluginInterface
:
namespace MyApi\ContaoManager;
use Contao\ManagerPlugin\Config\ContainerBuilder;
use Contao\ManagerPlugin\Config\ExtensionPluginInterface;
use HeimrichHannot\UtilsBundle\Container\ContainerUtil;
class Plugin implements ExtensionPluginInterface
{
/**
* {@inheritdoc}
*/
public function getExtensionConfig($extensionName, array $extensionConfigs, ContainerBuilder $container)
{
return ContainerUtil::mergeConfigFile(
'huh_api',
$extensionName,
$extensionConfigs,
__DIR__.'/../Resources/config/config.yml'
);
}
Do not forget to clear the symfony cache afterwards!
Now you are able to access your resource through /api/resource/my_resource
.
# test access to my_resource (provide your token from user or member login and your api key)
curl --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmXtZSI6ImRpZ2l0YWxlc0BoZWltcmljaA1oYW5ub3QuZGUiLCJpYXQiOjE1MzY4NTYwMDMsImV4cCI6MTUzNjk0MjQwM30.trp-1NgYgXGfHYdE3dlQ8awE8aXUWL-RfBQyfWm2Hz0" -H "Content-Type: application/json" -X GET http://domain.tld/api/resource/my_resource?key=<api-key>
Now you are able to access crud functionality by using the related HTTP method
:
# test create() new resource
curl --header "Authorization: Bearer <login-token>" -H "Content-Type: application/json" -X POST -d "{"title":"My test title", "published":true}" http://domain.tld/api/resource/my_resource?key=<api-key>
# test update() existing resource
curl --header "Authorization: Bearer <login-token>" -H "Content-Type: application/json" -X PUT -d "{"title":"My new test title", "published":false}" http://domain.tld/api/resource/my_resource/23?key=<api-key>
# test list() all resources
curl --header "Authorization: Bearer <login-token>" -H "Content-Type: application/json" -X GET http://domain.tld/api/resource/my_resource?key=<api-key>
# test show() existing resource
curl --header "Authorization: Bearer <login-token>" -H "Content-Type: application/json" -X GET http://domain.tld/api/resource/my_resource/23?key=<api-key>
# test delete() existing resource
curl --header "Authorization: Bearer <login-token>" -H "Content-Type: application/json" -X DELETE http://domain.tld/api/resource/my_resource/23?key=<api-key>
Available Resources
Service: huh.api.resource.member
Skeleton resource that provides simple crud functionality with contao member (tl_member) entity