remp / crm-api-module
CRM Api Module
Installs: 36 046
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 7
Forks: 4
Open Issues: 1
Requires
- php: ^8.1
- justinrainbow/json-schema: ^5.2
- spatie/array-to-xml: ^3.1
- tomaj/nette-api: ^2.6
- dev-master
- 3.4.0
- 3.3.0
- 3.2.0
- 3.1.0
- 3.0.0
- 2.11.0
- 2.10.0
- 2.9.0
- 2.8.0
- 2.7.0
- 2.6.0
- 2.5.0
- 2.4.0
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.0
- 1.2.3
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.0
- 1.0.0-beta2
- 1.0.0-beta1
- 0.39.0
- 0.38.0
- 0.37.0
- 0.36.0
- 0.35.0
- 0.34.0
- 0.33.0
- 0.32.0
- 0.31.0
- 0.30.0
- 0.29.0
- 0.28.0
- 0.27.0
- 0.26.0
- 0.25.0
- 0.24.0
- 0.23.0
- 0.22.0
- 0.21.0
- 0.20.0
- 0.18.0
- 0.17.0
- 0.16.0
- 0.15.0
- 0.14.0
- 0.13.0
- 0.12.0
- 0.11.0
- 0.10.0
- 0.9.0
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.0
- 0.6.0
- 0.5.0
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.10
- 0.2.9
- 0.2.8
- 0.2.7
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.1
- dev-release/1.2/api-module
This package is auto-updated.
Last update: 2024-09-20 12:56:16 UTC
README
This documentation serves as a complement to CRM Skeleton documentation related to creating and registering API handlers.
It describes API handlers provided by this module for others to use.
Enabling module
Make sure you add extension to your app/config/config.neon
file.
extensions: - Crm\ApiModule\DI\ApiModuleExtension
Configuration
Preflight requests
Module allows you to configure preflight request handling. Add following snippet to your config.neon
file:
services: # ... apiHeadersConfig: setup: - setAllowedOrigins('*') - setAllowedHeaders('Content-Type', 'Authorization', 'X-Requested-With') - setAllowedHttpMethods('*') - setAllowedCredentials(true) - setAccessControlMaxAge(600) # seconds
You can configure allowed origins by explicitly stating them or by using wildcards. Following configurations are valid:
setAllowedOrigins("*")
. Matches everythingsetAllowedOrigins("foo.bar", "*.foo.bar")
. Matchesfoo.bar
and all of its subdomains.setAllowedOrigins("foo.bar", "1.foo.bar")
. Matchesfoo.bar
,1.foo.bar
, but nothing else (nor any other subdomain).
API requests logging
You can globally enable or disable API logging in the CRM admin - config section. If the logging is enabled, you can further configure which specific paths should be logged or not.
We recommend using configuration of blacklist over whitelist. Otherwise you might encounter a scenario, where logs from one of our APIs might be missing when you need them.
To enable blacklist, add following snippet to your config.neon
file:
services: # ... apiLoggerConfig: setup: - setPathBlacklist([ Crm\ApiModule\Models\LoggerEndpointIdentifier('1', 'foo', 'bar'), ])
The LoggerEndpointIdentifier
requires three parameters: version
, package
and apiCall
- same parameters which you use when you register a new API handler. The snippet above will not log requests to the /api/v1/foo/bar
endpoint.
You can also use wildcards where necessary:
Crm\ApiModule\Models\LoggerEndpointIdentifier('*', 'foo', 'bar')
will match all requests going to/api/*/foo/bar
.Crm\ApiModule\Models\LoggerEndpointIdentifier('1', '*', '*')
will match all requests going to/api/v3/*/*
.
Blacklist and whitelist cannot be combined, the latter configured wins.
Data retention configuration
You can configure time before which application:cleanup
deletes old repository data and column which it uses by using (in your project configuration file):
apiLogsRepository: setup: - setRetentionThreshold('-2 months', 'created_at')
Database tables migration
Because of need of changing primary keys (int -> bigint), in tables that contain lots of data (or have risk of overflowing primary key if its int), we had to create migration process. Since some tables are very exposed and cannot be locked for more than a couple of seconds, we decided to create new tables, migrate the data manually and keep the old and new table in sync while migrating.
This migration process is necessary only for installations after specific version for specific table, and is two steps process.
Api logs migration (installed before version 2.5.0)
Consists of api_logs
table migration.
Steps:
- Run phinx migrations command
phinx:migrate
, which creates new tableapi_logs_v2
(in case there is no data in table, migration just changes type of primary key and next steps are not needed). - Run command
api:convert_api_logs_to_bigint
, which copies data from old table to new (e.g.api_logs
toapi_logs_v2
). Command will after successful migration atomically rename tables (e.g.api_logs
->api_logs_old
andapi_logs_v2
->api_logs
), so when the migration ends only new tables are used.
It's recommended to run application:bigint_migration_cleanup api_logs
command, at least 2 weeks (to preserve backup data, if some issue emerges) after successful migration to drop left-over tables.
API documentation
All examples use http://crm.press
as a base domain. Please change the host to the one you use
before executing the examples.
All examples use XXX
as a default value for authorization token, please replace it with the
real tokens:
- API tokens. Standard API keys for server-server communication. It identifies the calling application as a whole.
They can be generated in CRM Admin (
/api/api-tokens-admin/
) and each API key has to be whitelisted to access specific API endpoints. By default the API key has access to no endpoint. - User tokens. Generated for each user during the login process, token identify single user when communicating between
different parts of the system. The token can be read:
- From
n_token
cookie if the user was logged in via CRM. - From the response of
/api/v1/users/login
endpoint - you're free to store the response into your own cookie/local storage/session.
- From
API responses can contain following HTTP codes:
If possible, the response includes application/json
encoded payload with message explaining
the error further.
GET /api/v1/token/check
API servers for checking the validity of provided Bearer token within header.
Headers:
Example:
curl -v –X GET http://crm.press/api/v1/token/check \ -H "Content-Type:application/json" \ -H "Authorization: Bearer XXX"
Response:
{ "status": "ok" }