From 6532f3710cccbd77304e0bf63b193711644e276d Mon Sep 17 00:00:00 2001 From: pe7er Date: Tue, 4 Jun 2024 13:54:10 +0200 Subject: [PATCH 1/4] restructured General Concepts Web Services --- docs/general-concepts/webservices.md | 407 ------- docs/general-concepts/webservices/index.md | 16 + .../webservices/using-external-php.md | 202 +++ .../webservices/using-joomla-framework.md | 189 +++ .../webservices/webservices-core-endpoints.md | 1083 +++++++++++++++++ 5 files changed, 1490 insertions(+), 407 deletions(-) delete mode 100644 docs/general-concepts/webservices.md create mode 100644 docs/general-concepts/webservices/index.md create mode 100644 docs/general-concepts/webservices/using-external-php.md create mode 100644 docs/general-concepts/webservices/using-joomla-framework.md create mode 100644 docs/general-concepts/webservices/webservices-core-endpoints.md diff --git a/docs/general-concepts/webservices.md b/docs/general-concepts/webservices.md deleted file mode 100644 index 47c30759..00000000 --- a/docs/general-concepts/webservices.md +++ /dev/null @@ -1,407 +0,0 @@ -Web Services -============ - -Description of the webservices concept - -- Web Services are used to make systems COMMUNICATE each other by using the HTTP protocol and nowadays over TLS (Transport Layer Security). -- Another definition could be Web Services acts like a CONTRACT between a PRODUCER and a CONSUMER via ENDPOINTS. -- Simply put, Web Services are like doors and windows in a house, they are INPUTS and OUTPUTS to the OUTSIDE world. -- In the context on Joomla! as a system, Joomla Webservices API allows Joomla! to INTERACT WITH, EXTERNAL DATASOURCES. Like webapps, mobile,etc... - -## Communicate with the Joomla 4.x Web Services API -The communication with Joomla's Web Services API takes place via specified endpoints. - -- Joomla's core endpoints: https://docs.joomla.org/J4.x:Joomla_Core_APIs -- A collection of Joomla endpoints to use in Postman: https://github.com/alexandreelise/j4x-api-collection - -### Using the Joomla framework - -More often than not, when using the Joomla framework, under the hood it still uses cURL or php streams. Most of the cURL is available with your web hosting provider. Otherwise check phpinfo(); -You should be able to follow along because the examples using the Joomla framework will mimic those with cURL. - -#### Define some variables -First we define some variables that we use in all our cURL requests: -- the URL of your Joomla 4.x website and -- the Joomla's API Token of a Super User account or an account which has at least core.login.api permission and core.login.site to be able to see change current logged-in user's token. - - -```php -// Before passing the HTTP METHOD to CURL -use Joomla\Http\HttpFactory; -use Joomla\Uri\Uri; - -$http = (new HttpFactory())->getAvailableDriver(); -$url = 'https://example.org/api/index.php/v1'; -$uri = new Uri($url); - -// Put your Joomla! Api token in a safe place, for example a password manager or a vault storing secrets -// We should not use environment variables to store secrets. -// Here is why: https://www.trendmicro.com/en_us/research/22/h/analyzing-hidden-danger-of-environment-variables-for-keeping-secrets.html - -$token = ''; -``` - - -#### POST - Create an Article in the Category "Uncategorized" (Category ID = 2) - -```php -$categoryId = 2; // Joomla's default "Uncategorized" Category - -$data = [ -'title' => 'How to add an article to Joomla via the API?', -'alias' => 'how-to-add-article-via-joomla-api', -'articletext' => 'I have no idea...', -'catid' => $categoryId, -'language' => '*', -'metadesc' => '', -'metakey' => '', -]; - -$dataString = json_encode($data); - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -'Content-Length: ' . mb_strlen($dataString), -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -// Timeout in seconds -$timeout = 30; - -// Set path for creating an article it will set the current uri path part -$uri->setPath('content/articles'); - -// Will be a PSR-7 compatible Response -$response = $http->request('POST', $uri, $dataString, $headers, $timeout); - -// The response body is now a stream, so you need to do -echo $response->body; - -``` - -#### GET - Retrieve all articles from the "Uncategorized" Category - -```php -$categoryId = 2; // Joomla's default "Uncategorized" Category - -// Don't send payload to server -$dataString = null; - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -// Timeout in seconds -$timeout = 30; - -// Set path for getting all articles it will set the current uri path part -$uri->setPath('content/articles'); - -// Will be a PSR-7 compatible Response -$response = $http->request('GET', $uri, $dataString, $headers, $timeout); - -// The response body is now a stream, so you need to do -echo $response->body; - -``` - -#### GET - Retrieve one specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - -// Don't send payload to server -$dataString = null; - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -// Timeout in seconds -$timeout = 30; - -// Set path for getting a specific article it will set the current uri path part -$uri->setPath(sprintf('content/articles/%d', $articleId)); - -// Will be a PSR-7 compatible Response -$response = $http->request('GET', $uri, $dataString, $headers, $timeout); - -// The response body is now a stream, so you need to do -echo $response->body; - -``` - -#### PATCH - Modify a specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - -$data = [ -'id' => $articleId, -'title' => 'How to add an article via the Joomla 4 API?', -'introtext' => 'When using PATCH, articletext MUST be split into two parts or use at least just introtext in order to work properly', -'fulltext' => 'MORE CONTENT if you wish', -]; - -$dataString = json_encode($data); - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -'Content-Length: ' . mb_strlen($dataString), -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -// Timeout in seconds -$timeout = 30; - -// Set path for partial update of a specific article it will set the current uri path part -$uri->setPath(sprintf('content/articles/%d', $articleId)); - -// Will be a PSR-7 compatible Response -$response = $http->request('PATCH', $uri, $dataString, $headers, $timeout); - -// show response status code -echo $response->code; - -``` - -#### DELETE - Remove a specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - -// Don't send payload to server -$dataString = null; - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -// Timeout in seconds -$timeout = 30; - -// Set path for deleting of a specific article it will set the current uri path part -$uri->setPath(sprintf('content/articles/%d', $articleId)); - -// Will be a PSR-7 compatible Response -$response = $http->request('DELETE', $uri, $dataString, $headers, $timeout); - -// show response status code -echo $response->code; -``` - - -### Using the PHP cURL Functions - -The cURL functions needs to be available and enabled in your PHP configuration, check phpinfo(); - -#### Define some variables - -First we define some variables that we use in all our cURL requests: - -- the URL of your Joomla 4.x website and -- the Joomla's API Token of a Super User account or an account which has at least core.login.api permission and core.login.site to be able to see change current logged-in user's token. - -```php -// Before passing the HTTP METHOD to CURL -$curl = curl_init(); - -$url = 'https://example.org/api/index.php/v1'; - -// Put your Joomla! Api token in a safe place, for example a password manager or a vault storing secrets -// We should not use environment variables to store secrets. -// Here is why: https://www.trendmicro.com/en_us/research/22/h/analyzing-hidden-danger-of-environment-variables-for-keeping-secrets.html -$token = ''; -``` - -#### POST - Create an Article in the Category "Uncategorized" (Category ID = 2) - -```php -$categoryId = 2; // Joomla's default "Uncategorized" Category - - -$data = [ -'title' => 'How to add an article to Joomla via the API?', -'alias' => 'how-to-add-article-via-joomla-api', -'articletext' => 'I have no idea...', -'catid' => $categoryId, -'language' => '*', -'metadesc' => '', -'metakey' => '', -]; - -$dataString = json_encode($data); - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -'Content-Length: ' . mb_strlen($dataString), -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -curl_setopt_array($curl, [ - CURLOPT_URL => sprintf('%s/%s',$url,'content/articles'), - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => 'utf-8', - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_FOLLOWLOCATION => true, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, - CURLOPT_CUSTOMREQUEST => 'POST', - CURLOPT_POSTFIELDS => $dataString, - CURLOPT_HTTPHEADER => $headers, - ] -); - -$response = curl_exec($curl); -curl_close($curl); -echo $response; -``` - -#### GET - Retrieve all articles from the "Uncategorized" Category - -```php -$categoryId = 2; // Joomla's default "Uncategorized" Category - - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -curl_setopt_array($curl, [ - CURLOPT_URL => sprintf('%s/content/articles?filter[category]=%d',$url,$categoryId), - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => 'utf-8', - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_FOLLOWLOCATION => true, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, - CURLOPT_CUSTOMREQUEST => 'GET', - CURLOPT_HTTPHEADER => $headers, - ] -); - -$response = curl_exec($curl); -curl_close($curl); -echo $response; -``` - -#### GET - Retrieve one specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; -curl_setopt_array($curl, [ - CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => 'utf-8', - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_FOLLOWLOCATION => true, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, - CURLOPT_CUSTOMREQUEST => 'GET', - CURLOPT_HTTPHEADER => $headers, - ] -); - -$response = curl_exec($curl); -curl_close($curl); -echo $response; -``` - -#### PATCH - Modify a specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - - -$data = [ -'id' => $articleId, -'title' => 'How to add an article via the Joomla 4 API?', -'introtext' => 'When using PATCH, articletext MUST be split into two parts or use at least just introtext in order to work properly', -'fulltext' => 'MORE CONTENT if you wish', -]; - -$dataString = json_encode($data); - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -'Content-Length: ' . mb_strlen($dataString), -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -curl_setopt_array($curl, [ - CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => 'utf-8', - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_FOLLOWLOCATION => true, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, - CURLOPT_CUSTOMREQUEST => 'PATCH', - CURLOPT_POSTFIELDS => $dataString, - CURLOPT_HTTPHEADER => $headers, - ] -); - -$response = curl_exec($curl); -curl_close($curl); -echo $response; -``` - -#### DELETE - Remove a specific Article - -```php -$articleId = 1; // The Article ID of a specific Article - - -// HTTP request headers -$headers = [ -'Accept: application/vnd.api+json', -'Content-Type: application/json', -sprintf('X-Joomla-Token: %s', trim($token)), -]; - -curl_setopt_array($curl, [ - CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), - CURLOPT_RETURNTRANSFER => true, - CURLOPT_ENCODING => 'utf-8', - CURLOPT_MAXREDIRS => 10, - CURLOPT_TIMEOUT => 30, - CURLOPT_FOLLOWLOCATION => true, - CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, - CURLOPT_CUSTOMREQUEST => 'DELETE', - CURLOPT_HTTPHEADER => $headers, - ] -); - -$response = curl_exec($curl); -curl_close($curl); -echo $response; -``` diff --git a/docs/general-concepts/webservices/index.md b/docs/general-concepts/webservices/index.md new file mode 100644 index 00000000..8783a399 --- /dev/null +++ b/docs/general-concepts/webservices/index.md @@ -0,0 +1,16 @@ +Web Services +============ + +Description of the webservices concept + +- Web Services are used to make systems COMMUNICATE each other by using the HTTP protocol and nowadays over TLS (Transport Layer Security). +- Another definition could be Web Services acts like a CONTRACT between a PRODUCER and a CONSUMER via ENDPOINTS. +- Simply put, Web Services are like doors and windows in a house, they are INPUTS and OUTPUTS to the OUTSIDE world. +- In the context on Joomla! as a system, Joomla Webservices API allows Joomla! to INTERACT WITH, EXTERNAL DATASOURCES. Like webapps, mobile,etc... + +## Communicate with the Joomla 4.x Web Services API +The communication with Joomla's Web Services API takes place via specified endpoints. + +- Joomla's core endpoints: https://docs.joomla.org/J4.x:Joomla_Core_APIs +- A collection of Joomla endpoints to use in Postman: https://github.com/alexandreelise/j4x-api-collection + diff --git a/docs/general-concepts/webservices/using-external-php.md b/docs/general-concepts/webservices/using-external-php.md new file mode 100644 index 00000000..90e392f2 --- /dev/null +++ b/docs/general-concepts/webservices/using-external-php.md @@ -0,0 +1,202 @@ +Web Services using PHP cURL Functions +============ + +The cURL functions needs to be available and enabled in your PHP configuration, check phpinfo(); + +## Define some variables + +First we define some variables that we use in all our cURL requests: + +- the URL of your Joomla 4.x website and +- the Joomla's API Token of a Super User account or an account which has at least core.login.api permission and core.login.site to be able to see change current logged-in user's token. + +```php +// Before passing the HTTP METHOD to CURL +$curl = curl_init(); + +$url = 'https://example.org/api/index.php/v1'; + +// Put your Joomla! Api token in a safe place, for example a password manager or a vault storing secrets +// We should not use environment variables to store secrets. +// Here is why: https://www.trendmicro.com/en_us/research/22/h/analyzing-hidden-danger-of-environment-variables-for-keeping-secrets.html +$token = ''; +``` + +## POST - Create an Article in the Category "Uncategorized" (Category ID = 2) + +```php +$categoryId = 2; // Joomla's default "Uncategorized" Category + + +$data = [ +'title' => 'How to add an article to Joomla via the API?', +'alias' => 'how-to-add-article-via-joomla-api', +'articletext' => 'I have no idea...', +'catid' => $categoryId, +'language' => '*', +'metadesc' => '', +'metakey' => '', +]; + +$dataString = json_encode($data); + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +'Content-Length: ' . mb_strlen($dataString), +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +curl_setopt_array($curl, [ + CURLOPT_URL => sprintf('%s/%s',$url,'content/articles'), + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => 'utf-8', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 30, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, + CURLOPT_CUSTOMREQUEST => 'POST', + CURLOPT_POSTFIELDS => $dataString, + CURLOPT_HTTPHEADER => $headers, + ] +); + +$response = curl_exec($curl); +curl_close($curl); +echo $response; +``` + +## GET - Retrieve all articles from the "Uncategorized" Category + +```php +$categoryId = 2; // Joomla's default "Uncategorized" Category + + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +curl_setopt_array($curl, [ + CURLOPT_URL => sprintf('%s/content/articles?filter[category]=%d',$url,$categoryId), + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => 'utf-8', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 30, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, + CURLOPT_CUSTOMREQUEST => 'GET', + CURLOPT_HTTPHEADER => $headers, + ] +); + +$response = curl_exec($curl); +curl_close($curl); +echo $response; +``` + +## GET - Retrieve one specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; +curl_setopt_array($curl, [ + CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => 'utf-8', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 30, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, + CURLOPT_CUSTOMREQUEST => 'GET', + CURLOPT_HTTPHEADER => $headers, + ] +); + +$response = curl_exec($curl); +curl_close($curl); +echo $response; +``` + +## PATCH - Modify a specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + + +$data = [ +'id' => $articleId, +'title' => 'How to add an article via the Joomla 4 API?', +'introtext' => 'When using PATCH, articletext MUST be split into two parts or use at least just introtext in order to work properly', +'fulltext' => 'MORE CONTENT if you wish', +]; + +$dataString = json_encode($data); + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +'Content-Length: ' . mb_strlen($dataString), +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +curl_setopt_array($curl, [ + CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => 'utf-8', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 30, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, + CURLOPT_CUSTOMREQUEST => 'PATCH', + CURLOPT_POSTFIELDS => $dataString, + CURLOPT_HTTPHEADER => $headers, + ] +); + +$response = curl_exec($curl); +curl_close($curl); +echo $response; +``` + +## DELETE - Remove a specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +curl_setopt_array($curl, [ + CURLOPT_URL => sprintf('%s/content/articles/%d',$url,$articleId), + CURLOPT_RETURNTRANSFER => true, + CURLOPT_ENCODING => 'utf-8', + CURLOPT_MAXREDIRS => 10, + CURLOPT_TIMEOUT => 30, + CURLOPT_FOLLOWLOCATION => true, + CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2TLS, + CURLOPT_CUSTOMREQUEST => 'DELETE', + CURLOPT_HTTPHEADER => $headers, + ] +); + +$response = curl_exec($curl); +curl_close($curl); +echo $response; +``` diff --git a/docs/general-concepts/webservices/using-joomla-framework.md b/docs/general-concepts/webservices/using-joomla-framework.md new file mode 100644 index 00000000..cbdba0f2 --- /dev/null +++ b/docs/general-concepts/webservices/using-joomla-framework.md @@ -0,0 +1,189 @@ +Web Services using Joomla framework +============ + +More often than not, when using the Joomla framework, under the hood it still uses cURL or php streams. Most of the cURL is available with your web hosting provider. Otherwise check phpinfo(); +You should be able to follow along because the examples using the Joomla framework will mimic those with cURL. + +## Define some variables +First we define some variables that we use in all our cURL requests: +- the URL of your Joomla 4.x website and +- the Joomla's API Token of a Super User account or an account which has at least core.login.api permission and core.login.site to be able to see change current logged-in user's token. + + +```php +// Before passing the HTTP METHOD to CURL +use Joomla\Http\HttpFactory; +use Joomla\Uri\Uri; + +$http = (new HttpFactory())->getAvailableDriver(); +$url = 'https://example.org/api/index.php/v1'; +$uri = new Uri($url); + +// Put your Joomla! Api token in a safe place, for example a password manager or a vault storing secrets +// We should not use environment variables to store secrets. +// Here is why: https://www.trendmicro.com/en_us/research/22/h/analyzing-hidden-danger-of-environment-variables-for-keeping-secrets.html + +$token = ''; +``` + + +## POST - Create an Article in the Category "Uncategorized" (Category ID = 2) + +```php +$categoryId = 2; // Joomla's default "Uncategorized" Category + +$data = [ +'title' => 'How to add an article to Joomla via the API?', +'alias' => 'how-to-add-article-via-joomla-api', +'articletext' => 'I have no idea...', +'catid' => $categoryId, +'language' => '*', +'metadesc' => '', +'metakey' => '', +]; + +$dataString = json_encode($data); + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +'Content-Length: ' . mb_strlen($dataString), +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +// Timeout in seconds +$timeout = 30; + +// Set path for creating an article it will set the current uri path part +$uri->setPath('content/articles'); + +// Will be a PSR-7 compatible Response +$response = $http->request('POST', $uri, $dataString, $headers, $timeout); + +// The response body is now a stream, so you need to do +echo $response->body; + +``` + +## GET - Retrieve all articles from the "Uncategorized" Category + +```php +$categoryId = 2; // Joomla's default "Uncategorized" Category + +// Don't send payload to server +$dataString = null; + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +// Timeout in seconds +$timeout = 30; + +// Set path for getting all articles it will set the current uri path part +$uri->setPath('content/articles'); + +// Will be a PSR-7 compatible Response +$response = $http->request('GET', $uri, $dataString, $headers, $timeout); + +// The response body is now a stream, so you need to do +echo $response->body; + +``` + +## GET - Retrieve one specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + +// Don't send payload to server +$dataString = null; + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +// Timeout in seconds +$timeout = 30; + +// Set path for getting a specific article it will set the current uri path part +$uri->setPath(sprintf('content/articles/%d', $articleId)); + +// Will be a PSR-7 compatible Response +$response = $http->request('GET', $uri, $dataString, $headers, $timeout); + +// The response body is now a stream, so you need to do +echo $response->body; + +``` + +## PATCH - Modify a specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + +$data = [ +'id' => $articleId, +'title' => 'How to add an article via the Joomla 4 API?', +'introtext' => 'When using PATCH, articletext MUST be split into two parts or use at least just introtext in order to work properly', +'fulltext' => 'MORE CONTENT if you wish', +]; + +$dataString = json_encode($data); + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +'Content-Length: ' . mb_strlen($dataString), +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +// Timeout in seconds +$timeout = 30; + +// Set path for partial update of a specific article it will set the current uri path part +$uri->setPath(sprintf('content/articles/%d', $articleId)); + +// Will be a PSR-7 compatible Response +$response = $http->request('PATCH', $uri, $dataString, $headers, $timeout); + +// show response status code +echo $response->code; + +``` + +## DELETE - Remove a specific Article + +```php +$articleId = 1; // The Article ID of a specific Article + +// Don't send payload to server +$dataString = null; + +// HTTP request headers +$headers = [ +'Accept: application/vnd.api+json', +'Content-Type: application/json', +sprintf('X-Joomla-Token: %s', trim($token)), +]; + +// Timeout in seconds +$timeout = 30; + +// Set path for deleting of a specific article it will set the current uri path part +$uri->setPath(sprintf('content/articles/%d', $articleId)); + +// Will be a PSR-7 compatible Response +$response = $http->request('DELETE', $uri, $dataString, $headers, $timeout); + +// show response status code +echo $response->code; +``` diff --git a/docs/general-concepts/webservices/webservices-core-endpoints.md b/docs/general-concepts/webservices/webservices-core-endpoints.md new file mode 100644 index 00000000..53626b00 --- /dev/null +++ b/docs/general-concepts/webservices/webservices-core-endpoints.md @@ -0,0 +1,1083 @@ +Web Services Core Endpoints +============ + +## Banners + +### Banners +#### Get List of Banners[edit] +```bash +curl -X GET /api/index.php/v1/banners +``` +#### Get Single Banner[edit] +```bash +curl -X GET /api/index.php/v1/banners/{banner_id} +``` +#### Delete Banner[edit] +```bash +curl -X DELETE /api/index.php/v1/banners/{banner_id} +``` +#### Create Banner[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners -d +``` +```json +{ +"catid": 3, +"clicks": 0, +"custombannercode": "", +"description": "Text", +"metakey": "", +"name": "Name", +"params": { + "alt": "", + "height": "", + "imageurl": "", + "width": "" +} +} +``` +#### Update Banner[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/{banner_id} -d +``` +```json +{ +"alias": "name", +"catid": 3, +"description": "New Text", +"name": "New Name" +} +``` + +### Clients[edit] +#### Get List of Clients[edit] +```bash +curl -X GET /api/index.php/v1/banners/clients +``` + +#### Get Single Client[edit] +```bash +curl -X GET /api/index.php/v1/banners/clients/{client_id} +``` + +#### Delete Client[edit] +```bash +curl -X DELETE /api/index.php/v1/banners/clients/{client_id} +``` + +#### Create Client[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/clients -d +``` +```json +{ +"contact": "Name", +"email": "email@mail.com", +"extrainfo": "", +"metakey": "", +"name": "Clients", +"state": 1 +} +``` + +#### Update Client[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/clients/{client_id} -d +``` +```json +{ +"contact": "new Name", +"email": "newemail@mail.com", +"name": "Clients" +} +``` +### Categories[edit] +#### Get List of Categories[edit] +```bash +curl -X GET /api/index.php/v1/banners/categories +``` +#### Get Single Category[edit] +```bash +curl -X GET /api/index.php/v1/banners/categories/{category_id} +``` +#### Delete Category[edit] +```bash +curl -X DELETE /api/index.php/v1/banners/categories/{category_id} +``` +#### Create Category[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/categories -d +``` +```json +{ +"access": 1, +"alias": "cat", +"extension": "com_banners", +"language": "*", +"note": "", +"parent_id": 1, +"published": 1, +"title": "Title" +} +``` +#### Update Category[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/categories/{category_id} -d +``` +```json +{ +"alias": "cat", +"note": "Some Text", +"parent_id": 1, +"title": "New Title" +} +``` +### Content History[edit] +#### Get List of Content Histories[edit] +```bash +curl -X GET /api/index.php/v1/banners/contenthistory/{banner_id} +``` +#### Toggle Keep Content History[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/contenthistory/keep/{contenthistory_id} +``` +#### Delete Content History[edit] +```bash +curl -X DELETE /api/index.php/v1/banners/contenthistory/{contenthistory_id} +``` +## Config[edit] +### Application[edit] +#### Get List of Application Configs[edit] +```bash +curl -X GET /api/index.php/v1/config/application +``` +#### Update Application Config[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/application -d +``` +```json +{ +"debug": true, +"sitename": "123" +} +``` +### Component[edit] +#### Get List of Component Configs[edit] +```bash +curl -X GET /api/index.php/v1/config/{component_name} +``` +Example “component_name” is “com_content”. + +#### Update Application Config[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/application -d +``` +```json +{ +"link_titles": 1 +} +``` + +## Contact[edit] +### Contact[edit] +#### Get List of Contacts[edit] +```bash +curl -X GET /api/index.php/v1/contacts +``` +#### Get Single Contact[edit] +```bash +curl -X GET /api/index.php/v1/contacts/{contact_id} +``` +#### Delete Contact[edit] +```bash +curl -X DELETE /api/index.php/v1/contacts/{contact_id} +``` +#### Create Contact[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts -d +``` +```json +{ +"alias": "contact", +"catid": 4, +"language": "*", +"name": "Contact" +} +``` +#### Update Contact[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/contacts/{contact_id} -d +``` +```json +{ +"alias": "contact", +"catid": 4, +"name": "New Contact" +} +``` +#### Submit Contact Form[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts/form/{contact_id} -d +``` +```json +{ +"contact_email": "email@mail.com", +"contact_message": "some text", +"contact_name": "name", +"contact_subject": "subject" +} +``` +### Categories[edit] +- Route Contact Categories is: "v1/contacts/categories" +- Working with it is similar to Banners Categories. +### Fields Contact[edit] +#### Get List of Fields Contact[edit] +```bash +curl -X GET /api/index.php/v1/fields/contacts/contact +``` +#### Get Single Field Contact[edit] +```bash +curl -X GET /api/index.php/v1/fields/contacts/contact/{field_id} +``` +#### Delete Field Contact[edit] +```bash +curl -X DELETE /api/index.php/v1/fields/contacts/contact/{field_id} +``` +#### Create Field Contact[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/contacts/contact -d +``` +```json +{ +"access": 1, +"context": "com_contact.contact", +"default_value": "", +"description": "", +"group_id": 0, +"label": "contact field", +"language": "*", +"name": "contact-field", +"note": "", +"params": { + "class": "", + "display": "2", + "display_readonly": "2", + "hint": "", + "label_class": "", + "label_render_class": "", + "layout": "", + "prefix": "", + "render_class": "", + "show_on": "", + "showlabel": "1", + "suffix": "" +}, +"required": 0, +"state": 1, +"title": "contact field", +"type": "text" +} +``` +#### Update Field Contact[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/contacts/contact/{field_id} -d +``` +```json +{ +"title": "new contact field", +"name": "contact-field", +"label": "contact field", +"default_value": "", +"type": "text", +"note": "", +"description": "Some New Text" +} +``` +### Fields Contact Mail[edit] +- Route Fields Contact Mail is: "v1/fields/contacts/mail" +- Working with it is similar to Fields Contact. +### Fields Contact Categories[edit] +- Route Fields Contact Categories is: "v1/fields/contacts/categories" +- Working with it is similar to Fields Contact. +### Groups Fields Contact[edit] +#### Get List of Groups Fields Contact[edit] +```bash +curl -X GET /api/index.php/v1/fields/groups/contacts/contact +``` +#### Get Single Group Fields Contact[edit] +```bash +curl -X GET /api/index.php/v1/fields/groups/contacts/contact/{group_id} +``` +#### Delete Group Fields Contact[edit] +```bash +curl -X DELETE /api/index.php/v1/fields/groups/contacts/contact/{group_id} +``` +#### Create Group Fields Contact[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact -d +``` +```json +{ +"access": 1, +"context": "com_contact.contact", +"default_value": "", +"description": "", +"group_id": 0, +"label": "contact field", +"language": "*", +"name": "contact-field3", +"note": "", +"params": { + "class": "", + "display": "2", + "display_readonly": "2", + "hint": "", + "label_class": "", + "label_render_class": "", + "layout": "", + "prefix": "", + "render_class": "", + "show_on": "", + "showlabel": "1", + "suffix": "" +}, +"required": 0, +"state": 1, +"title": "contact field", +"type": "text" +} +``` +#### Update Group Fields Contact[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact/{group_id} -d +``` +```json +{ +"title": "new contact group", +"note": "", +"description": "new description" +} +``` +### Group Fields Contact Mail[edit] +- Route Group Fields Contact Mail is: "v1/fields/groups/contacts/mail" +- Working with it is similar to Group Fields Contact. +### Group Fields Contact Categories[edit] +- Route Group Fields Contact Categories is: "v1/fields/groups/contacts/categories" +- Working with it is similar to Group Fields Contact. +### Content History[edit] +- Route Content History is: "v1/contacts/{groupid}/contenthistory" +- Working with it is similar to Banners Content History. + +## Content[edit] +### Articles[edit] +#### Get List of Articles[edit] +```bash +curl -X GET /api/index.php/v1/content/articles +``` +#### Get Single Article[edit] +```bash +curl -X GET /api/index.php/v1/content/articles/{article_id} +``` +#### Delete Article[edit] +```bash +curl -X DELETE /api/index.php/v1/content/articles/{article_id} +``` +#### Create Article[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/content/articles -d +``` +```json +{ +"alias": "my-article", +"articletext": "My text", +"catid": 64, +"language": "*", +"metadesc": "", +"metakey": "", +"title": "Here's an article" +} +``` +Currently the options mentioned here are required properties. However the intention is currently to make at least metakey and metadesc optional in the API. + +#### Update Article[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/articles/{article_id} -d +``` +```json +{ +"catid": 64, +"title": "Updated article" +} +``` +### Categories[edit] +- Route Content Categories is: "v1/content/categories" +- Working with it is similar to Banners Categories, note if workflows is enabled then specifying a workflow is required (similarly to the UI). +### Fields Articles[edit] +- Route Fields Articles is: "v1/fields/content/articles" +- Working with it is similar to Fields Contact. +### Groups Fields Articles[edit] +- Route Groups Fields Articles is: "v1/fields/groups/content/articles" +- Working with it is similar to Groups Fields Contact. +### Fields Categories[edit] +- Route Fields Categories is: "v1/fields/groups/content/categories" +- Working with it is similar to Fields Contact. +### Content History[edit] +- Route Content History is: "v1/content/articles/{article_id}/contenthistory" +- Working with it is similar to Banners Content History. + +## Languages[edit] +### Languages[edit] +#### Get List of Languages[edit] +```bash +curl -X GET /api/index.php/v1/languages +``` +#### Install Language[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages -d +``` +```json +{ +"package": "pkg_fr-FR" +} +``` +### Content Languages[edit] +#### Get List of Content Languages[edit] +```bash +curl -X GET /api/index.php/v1/languages/content +``` +#### Get Single Content Language[edit] +```bash +curl -X GET /api/index.php/v1/v1/languages/content/{language_id} +``` +#### Delete Content Language[edit] +```bash +curl -X DELETE /api/index.php/v1/languages/content/{language_id} +``` +#### Create Content Language[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/content -d +``` +```json +{ +"access": 1, +"description": "", +"image": "fr_FR", +"lang_code": "fr-FR", +"metadesc": "", +"metakey": "", +"ordering": 1, +"published": 0, +"sef": "fk", +"sitename": "", +"title": "French (FR)", +"title_native": "Français (France)" +} +``` +#### Update Content Language[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/content/{language_id} -d +``` +```json +{ +"description": "", +"lang_code": "en-GB", +"metadesc": "", +"metakey": "", +"sitename": "", +"title": "English (en-GB)", +"title_native": "English (United Kingdom)" +} +``` +### Overrides Languages[edit] +#### Get List of Overrides Languages Constants[edit] +```bash +curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code} +``` +#### Get Single Override Language Constant[edit] +```bash +curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} +``` +#### Delete Content Language[edit] +```bash +curl -X DELETE /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} +``` +#### Create Content Language[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code} -d +``` +```json +{ +"key":"new_key", +"override": "text" +} +``` +#### Update Content Language[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} -d +``` +```json +{ +"key":"new_key", +"override": "new text" +} +``` +- var app - enum {"site", "administrator"} +- var lang_code - string Example: “fr-FR“, “en-GB“ you can get lang_code from v1/languages/content + +#### Search Override Constant[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/search -d +``` +```json +{ +"searchstring": "JLIB_APPLICATION_ERROR_SAVE_FAILED", +"searchtype": "constant" +} +``` +- var searchtype - enum {“constant”, “value”}. “constant” search by constant name, “value” - search by constant value +#### Refresh Override Search Cache[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/search/cache/refresh +``` + +## Menus[edit] +### Menus[edit] +#### Get List of Menus[edit] +```bash +curl -X GET /api/index.php/v1/menus/{app} +``` +#### Get Single Menu[edit] +```bash +curl -X GET /api/index.php/v1/menus/{app}/{menu_id} +``` +#### Delete Menu[edit] +```bash +curl -X DELETE /api/index.php/v1/menus/{app}/{menu_id} +``` +#### Create Menu[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app} -d +``` +```json +{ +"client_id": 0, +"description": "The menu for the site", +"menutype": "menu", +"title": "Menu" +} +``` +#### Update Menu[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/{menu_id} -d +``` +```json +{ +"menutype": "menu", +"title": "New Menu" +} +``` +### Menus Items[edit] +#### Get List of Menus Items Types[edit] +```bash +curl -X GET /api/index.php/v1/menus/{app}/items/types +``` +#### Get List of Menus Items[edit] +```bash +curl -X GET /api/index.php/v1/menus/{app}/items +``` +#### Get Single Menu Item[edit] +```bash +curl -X GET /api/index.php/v1/menus/{app}/items/{menu_item_id} +``` +#### Delete Menu Item[edit] +```bash +curl -X DELETE /api/index.php/v1/menus/{app}/items/{menu_item_id} +``` +#### Create Menu Item[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items -d +``` +```json +{ +"access": "1", +"alias": "", +"associations": { + "en-GB": "", + "fr-FR": "" +}, +"browserNav": "0", +"component_id": "20", +"home": "0", +"language": "*", +"link": "index.php?option=com_content&view=form&layout=edit", +"menutype": "mainmenu", +"note": "", +"params": { + "cancel_redirect_menuitem": "", + "catid": "", + "custom_cancel_redirect": "0", + "enable_category": "0", + "menu-anchor_css": "", + "menu-anchor_title": "", + "menu-meta_description": "", + "menu-meta_keywords": "", + "menu_image": "", + "menu_image_css": "", + "menu_show": "1", + "menu_text": "1", + "page_heading": "", + "page_title": "", + "pageclass_sfx": "", + "redirect_menuitem": "", + "robots": "", + "show_page_heading": "" +}, +"parent_id": "1", +"publish_down": "", +"publish_up": "", +"published": "1", +"template_style_id": "0", +"title": "title", +"toggle_modules_assigned": "1", +"toggle_modules_published": "1", +"type": "component" +} +``` +- Example for "Create Article Page" + +#### Update Menu Item[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items/{menu_item_id} -d +``` +```json +{ +"component_id": "20", +"language": "*", +"link": "index.php?option=com_content&view=form&layout=edit", +"menutype": "mainmenu", +"note": "", +"title": "new title", +"type": "component" +} +``` +- Example for "Create Article Page" + +## Messages[edit] +### Messages[edit] +#### Get List of Messages[edit] +```bash +curl -X GET /api/index.php/v1/messages +``` +#### Get Single Message[edit] +```bash +curl -X GET /api/index.php/v1/messages/{message_id} +``` +#### Delete Message[edit] +```bash +curl -X DELETE /api/index.php/v1/messages/{message_id} +``` +#### Create Message[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/messages -d +``` +```json +{ +"message": "

text

", +"state": 0, +"subject": "text", +"user_id_from": 773, +"user_id_to": 772 +} +``` +#### Update Message[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/{message_id} -d +``` +```json +{ +"message": "

new text

", +"subject": "new text", +"user_id_from": 773, +"user_id_to": 772 +} +``` + +## Modules[edit] +### Modules[edit] +#### Get List of Modules Types[edit] +```bash +curl -X GET /api/index.php/v1/modules/types/{app} +``` +#### Get List of Modules[edit] +```bash +curl -X GET /api/index.php/v1/modules/{app} +``` +#### Get Single Module[edit] +```bash +curl -X GET /api/index.php/v1/modules/{app}/{module_id} +``` +#### Delete Module[edit] +```bash +curl -X DELETE /api/index.php/v1/modules/{app}/{module_id} +``` +#### Create Module[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/{app} -d +``` +```json +{ +"access": "1", +"assigned": [ + "101", + "105" +], +"assignment": "0", +"client_id": "0", +"language": "*", +"module": "mod_articles_archive", +"note": "", +"ordering": "1", +"params": { + "bootstrap_size": "0", + "cache": "1", + "cache_time": "900", + "cachemode": "static", + "count": "10", + "header_class": "", + "header_tag": "h3", + "layout": "_:default", + "module_tag": "div", + "moduleclass_sfx": "", + "style": "0" +}, +"position": "", +"publish_down": "", +"publish_up": "", +"published": "1", +"showtitle": "1", +"title": "Title" +} +``` +- Example for "Articles - Archived" + +#### Update Module[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/modules/{app}/{module_id} -d +``` +```json +{ +"access": "1", +"client_id": "0", +"language": "*", +"module": "mod_articles_archive", +"note": "", +"ordering": "1", +"title": "New Title" +} +``` +- Example for "Articles - Archived" + +## Newsfeeds[edit] +### Feeds[edit] +#### Get List of Feeds[edit] +```bash +curl -X GET /api/index.php/v1/newsfeeds/feeds +``` +#### Get Single Feed[edit] +```bash +curl -X GET /api/index.php/v1/newsfeeds/feeds/{feed_id} +``` +#### Delete Feed[edit] +```bash +curl -X DELETE /api/index.php/v1/newsfeeds/feeds/{feed_id} +``` +#### Create Feed[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/feeds -d +``` +```json +{ +"access": 1, +"alias": "alias", +"catid": 5, +"description": "", +"images": { + "float_first": "", + "float_second": "", + "image_first": "", + "image_first_alt": "", + "image_first_caption": "", + "image_second": "", + "image_second_alt": "", + "image_second_caption": "" +}, +"language": "*", +"link": "https://github.com/joomla-projects/gsoc19_webservices", +"metadata": { + "hits": "", + "rights": "", + "robots": "", + "tags": { + "tags": "", + "typeAlias": null + } +}, +"metadesc": "", +"metakey": "", +"name": "Name", +"ordering": 1, +"params": { + "feed_character_count": "", + "feed_display_order": "", + "newsfeed_layout": "", + "show_feed_description": "", + "show_feed_image": "", + "show_item_description": "" +}, +"published": 1 +} +``` +#### Update Feed[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/feeds/{feed_id} -d +``` +```json +{ +"access": 1, +"alias": "test2", +"catid": 5, +"description": "", +"link": "https://github.com/joomla-projects/gsoc19_webservices", +"metadesc": "", +"metakey": "", +"name": "Test" +} +``` +### Categories[edit] +- Route Newsfeeds Categories is: "v1/newsfeeds/categories" +- Working with it is similar to Banners Categories. + +## Privacy[edit] +### Request[edit] +#### Get List of Requests[edit] +```bash +curl -X GET /api/index.php/v1/privacy/requests +``` +#### Get Single Request[edit] +```bash +curl -X GET /api/index.php/v1/privacy/requests/{request_id} +``` +#### Get Single Request Export Data[edit] +```bash +curl -X GET /api/index.php/v1/privacy/request/export/{request_id} +``` +#### Create Request[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/privacy/requests -d +``` +```json +{ +"email":"somenewemail@com.ua", +"request_type":"export" +} +``` +### Consent[edit] +#### Get List of Consents[edit] +```bash +curl -X GET /api/index.php/v1/privacy/consents +``` +#### Get Single Consent[edit] +```bash +curl -X GET /api/index.php/v1/privacy/consents/{consent_id} +``` + +## Redirect[edit] +### Redirect[edit] +#### Get List of Redirects[edit] +```bash +curl -X GET /api/index.php/v1/redirect +``` +#### Get Single Redirect[edit] +```bash +curl -X GET /api/index.php/v1/redirect/{redirect_id} +``` +#### Delete Redirect[edit] +```bash +curl -X DELETE /api/index.php/v1/redirect/{redirect_id} +``` +#### Create Redirect[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/redirect -d +``` +```json +{ +"comment": "", +"header": 301, +"hits": 0, +"new_url": "/content/art/99", +"old_url": "/content/art/12", +"published": 1, +"referer": "" +} +``` +#### Update Redirect[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/redirect/{redirect_id} -d +``` +```json +{ +"new_url": "/content/art/4", +"old_url": "/content/art/132" +} +``` + +## Tags[edit] +### Tags[edit] +#### Get List of Tags[edit] +```bash +curl -X GET /api/index.php/v1/tags +``` +#### Get Single Tag[edit] +```bash +curl -X GET /api/index.php/v1/tags/{tag_id} +``` +#### Delete Tag[edit] +```bash +curl -X DELETE /api/index.php/v1/tags/{tag_id} +``` +#### Create Tag[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/tags -d +``` +```json +{ +"access": 1, +"access_title": "Public", +"alias": "test", +"description": "", +"language": "*", +"note": "", +"parent_id": 1, +"path": "test", +"published": 1, +"title": "test" +} +``` +#### Update Tag[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/{tag_id} -d +``` +```json +{ +"alias": "test", +"title": "new title" +} +``` +## Templates[edit] +### Templates Styles[edit] +#### Get List of Templates Styles[edit] +```bash +curl -X GET /api/index.php/v1/templates/styles/{app} +``` +#### Get Single Template Style[edit] +```bash +curl -X GET /api/index.php/v1/templates/styles/{app}/{template_style_id} +``` +#### Delete Template Style[edit] +```bash +curl -X DELETE /api/index.php/v1/templates/styles/{app}/{template_style_id} +``` +#### Create Template Style[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app} -d +``` +```json +{ +"home": "0", +"params": { + "fluidContainer": "0", + "logoFile": "", + "sidebarLeftWidth": "3", + "sidebarRightWidth": "3" +}, +"template": "cassiopeia", +"title": "cassiopeia - Some Text" +} +``` +#### Update Template Style[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app}/{template_style_id} -d +``` +```json +{ +"template": "cassiopeia", +"title": "new cassiopeia - Default" +} +``` + +## Users[edit] +### Users[edit] +#### Get List of Users[edit] +```bash +curl -X GET /api/index.php/v1/users +``` +#### Get Single User[edit] +```bash +curl -X GET /api/index.php/v1/users/{user_id} +``` +#### Delete User[edit] +```bash +curl -X DELETE /api/index.php/v1/users/{user_id} +``` +#### Create User[edit] +```bash +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/users -d +``` +```json +{ +"block": "0", +"email": "test@mail.com", +"groups": [ + "2" +], +"id": "0", +"lastResetTime": "", +"lastvisitDate": "", +"name": "nnn", +"params": { + "admin_language": "", + "admin_style": "", + "editor": "", + "helpsite": "", + "language": "", + "timezone": "" +}, +"password": "qwertyqwerty123", +"password2": "qwertyqwerty123", +"registerDate": "", +"requireReset": "0", +"resetCount": "0", +"sendEmail": "0", +"username": "ad" +} +``` +#### Update User[edit] +```bash +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/users/{user_id} -d +``` +```json +{ +"email": "new@mail.com", +"groups": [ + "2" +], +"name": "name", +"username": "username" +} +``` +### Fields Users[edit] +- Route Fields Users is: v1/fields/users +- Working with it is similar to Fields Contact. +### Groups Fields Users[edit] +- Route Groups Fields Users is: v1/fields/groups/users +- Working with it is similar to Groups Fields Contact. \ No newline at end of file From fff58781b2613ae667051136b390110cbda1a599 Mon Sep 17 00:00:00 2001 From: pe7er Date: Tue, 4 Jun 2024 14:04:14 +0200 Subject: [PATCH 2/4] restructured General Concepts Web Services --- .../webservices/webservices-core-endpoints.md | 327 +++++++++--------- 1 file changed, 165 insertions(+), 162 deletions(-) diff --git a/docs/general-concepts/webservices/webservices-core-endpoints.md b/docs/general-concepts/webservices/webservices-core-endpoints.md index 53626b00..632743f4 100644 --- a/docs/general-concepts/webservices/webservices-core-endpoints.md +++ b/docs/general-concepts/webservices/webservices-core-endpoints.md @@ -1,22 +1,25 @@ Web Services Core Endpoints ============ -## Banners +:::tip[Developer Note] +TODO: add internal links to this document, see https://docs.joomla.org/J4.x:Joomla_Core_APIs +::: +## Banners ### Banners -#### Get List of Banners[edit] +#### Get List of Banners ```bash curl -X GET /api/index.php/v1/banners ``` -#### Get Single Banner[edit] +#### Get Single Banner ```bash curl -X GET /api/index.php/v1/banners/{banner_id} ``` -#### Delete Banner[edit] +#### Delete Banner ```bash curl -X DELETE /api/index.php/v1/banners/{banner_id} ``` -#### Create Banner[edit] +#### Create Banner ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners -d ``` @@ -36,7 +39,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners -d } } ``` -#### Update Banner[edit] +#### Update Banner ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/{banner_id} -d ``` @@ -49,23 +52,23 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/{ban } ``` -### Clients[edit] -#### Get List of Clients[edit] +### Clients +#### Get List of Clients ```bash curl -X GET /api/index.php/v1/banners/clients ``` -#### Get Single Client[edit] +#### Get Single Client ```bash curl -X GET /api/index.php/v1/banners/clients/{client_id} ``` -#### Delete Client[edit] +#### Delete Client ```bash curl -X DELETE /api/index.php/v1/banners/clients/{client_id} ``` -#### Create Client[edit] +#### Create Client ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/clients -d ``` @@ -80,7 +83,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/clien } ``` -#### Update Client[edit] +#### Update Client ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/clients/{client_id} -d ``` @@ -91,20 +94,20 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/clie "name": "Clients" } ``` -### Categories[edit] -#### Get List of Categories[edit] +### Categories +#### Get List of Categories ```bash curl -X GET /api/index.php/v1/banners/categories ``` -#### Get Single Category[edit] +#### Get Single Category ```bash curl -X GET /api/index.php/v1/banners/categories/{category_id} ``` -#### Delete Category[edit] +#### Delete Category ```bash curl -X DELETE /api/index.php/v1/banners/categories/{category_id} ``` -#### Create Category[edit] +#### Create Category ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/categories -d ``` @@ -120,7 +123,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/banners/categ "title": "Title" } ``` -#### Update Category[edit] +#### Update Category ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/categories/{category_id} -d ``` @@ -132,26 +135,26 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/cate "title": "New Title" } ``` -### Content History[edit] -#### Get List of Content Histories[edit] +### Content History +#### Get List of Content Histories ```bash curl -X GET /api/index.php/v1/banners/contenthistory/{banner_id} ``` -#### Toggle Keep Content History[edit] +#### Toggle Keep Content History ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/banners/contenthistory/keep/{contenthistory_id} ``` -#### Delete Content History[edit] +#### Delete Content History ```bash curl -X DELETE /api/index.php/v1/banners/contenthistory/{contenthistory_id} ``` -## Config[edit] -### Application[edit] -#### Get List of Application Configs[edit] +## Config +### Application +#### Get List of Application Configs ```bash curl -X GET /api/index.php/v1/config/application ``` -#### Update Application Config[edit] +#### Update Application Config ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/application -d ``` @@ -161,14 +164,14 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/appli "sitename": "123" } ``` -### Component[edit] -#### Get List of Component Configs[edit] +### Component +#### Get List of Component Configs ```bash curl -X GET /api/index.php/v1/config/{component_name} ``` Example “component_name” is “com_content”. -#### Update Application Config[edit] +#### Update Application Config ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/application -d ``` @@ -178,21 +181,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/appli } ``` -## Contact[edit] -### Contact[edit] -#### Get List of Contacts[edit] +## Contact +### Contact +#### Get List of Contacts ```bash curl -X GET /api/index.php/v1/contacts ``` -#### Get Single Contact[edit] +#### Get Single Contact ```bash curl -X GET /api/index.php/v1/contacts/{contact_id} ``` -#### Delete Contact[edit] +#### Delete Contact ```bash curl -X DELETE /api/index.php/v1/contacts/{contact_id} ``` -#### Create Contact[edit] +#### Create Contact ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts -d ``` @@ -204,7 +207,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts -d "name": "Contact" } ``` -#### Update Contact[edit] +#### Update Contact ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/contacts/{contact_id} -d ``` @@ -215,7 +218,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/contacts/{co "name": "New Contact" } ``` -#### Submit Contact Form[edit] +#### Submit Contact Form ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts/form/{contact_id} -d ``` @@ -227,23 +230,23 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/contacts/form "contact_subject": "subject" } ``` -### Categories[edit] +### Categories - Route Contact Categories is: "v1/contacts/categories" -- Working with it is similar to Banners Categories. -### Fields Contact[edit] -#### Get List of Fields Contact[edit] +- Working with it is similar to [Banners Categories](#BannersCategories). +### Fields Contact +#### Get List of Fields Contact ```bash curl -X GET /api/index.php/v1/fields/contacts/contact ``` -#### Get Single Field Contact[edit] +#### Get Single Field Contact ```bash curl -X GET /api/index.php/v1/fields/contacts/contact/{field_id} ``` -#### Delete Field Contact[edit] +#### Delete Field Contact ```bash curl -X DELETE /api/index.php/v1/fields/contacts/contact/{field_id} ``` -#### Create Field Contact[edit] +#### Create Field Contact ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/contacts/contact -d ``` @@ -278,7 +281,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/contac "type": "text" } ``` -#### Update Field Contact[edit] +#### Update Field Contact ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/contacts/contact/{field_id} -d ``` @@ -293,26 +296,26 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/conta "description": "Some New Text" } ``` -### Fields Contact Mail[edit] +### Fields Contact Mail - Route Fields Contact Mail is: "v1/fields/contacts/mail" - Working with it is similar to Fields Contact. -### Fields Contact Categories[edit] +### Fields Contact Categories - Route Fields Contact Categories is: "v1/fields/contacts/categories" - Working with it is similar to Fields Contact. -### Groups Fields Contact[edit] -#### Get List of Groups Fields Contact[edit] +### Groups Fields Contact +#### Get List of Groups Fields Contact ```bash curl -X GET /api/index.php/v1/fields/groups/contacts/contact ``` -#### Get Single Group Fields Contact[edit] +#### Get Single Group Fields Contact ```bash curl -X GET /api/index.php/v1/fields/groups/contacts/contact/{group_id} ``` -#### Delete Group Fields Contact[edit] +#### Delete Group Fields Contact ```bash curl -X DELETE /api/index.php/v1/fields/groups/contacts/contact/{group_id} ``` -#### Create Group Fields Contact[edit] +#### Create Group Fields Contact ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact -d ``` @@ -347,7 +350,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/groups "type": "text" } ``` -#### Update Group Fields Contact[edit] +#### Update Group Fields Contact ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact/{group_id} -d ``` @@ -358,31 +361,31 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/group "description": "new description" } ``` -### Group Fields Contact Mail[edit] +### Group Fields Contact Mail - Route Group Fields Contact Mail is: "v1/fields/groups/contacts/mail" - Working with it is similar to Group Fields Contact. -### Group Fields Contact Categories[edit] +### Group Fields Contact Categories - Route Group Fields Contact Categories is: "v1/fields/groups/contacts/categories" - Working with it is similar to Group Fields Contact. -### Content History[edit] +### Content History - Route Content History is: "v1/contacts/{groupid}/contenthistory" - Working with it is similar to Banners Content History. -## Content[edit] -### Articles[edit] -#### Get List of Articles[edit] +## Content +### Articles +#### Get List of Articles ```bash curl -X GET /api/index.php/v1/content/articles ``` -#### Get Single Article[edit] +#### Get Single Article ```bash curl -X GET /api/index.php/v1/content/articles/{article_id} ``` -#### Delete Article[edit] +#### Delete Article ```bash curl -X DELETE /api/index.php/v1/content/articles/{article_id} ``` -#### Create Article[edit] +#### Create Article ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/content/articles -d ``` @@ -399,7 +402,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/content/artic ``` Currently the options mentioned here are required properties. However the intention is currently to make at least metakey and metadesc optional in the API. -#### Update Article[edit] +#### Update Article ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/articles/{article_id} -d ``` @@ -409,29 +412,29 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/arti "title": "Updated article" } ``` -### Categories[edit] +### Categories - Route Content Categories is: "v1/content/categories" - Working with it is similar to Banners Categories, note if workflows is enabled then specifying a workflow is required (similarly to the UI). -### Fields Articles[edit] +### Fields Articles - Route Fields Articles is: "v1/fields/content/articles" - Working with it is similar to Fields Contact. -### Groups Fields Articles[edit] +### Groups Fields Articles - Route Groups Fields Articles is: "v1/fields/groups/content/articles" - Working with it is similar to Groups Fields Contact. -### Fields Categories[edit] +### Fields Categories - Route Fields Categories is: "v1/fields/groups/content/categories" - Working with it is similar to Fields Contact. -### Content History[edit] +### Content History - Route Content History is: "v1/content/articles/{article_id}/contenthistory" - Working with it is similar to Banners Content History. -## Languages[edit] -### Languages[edit] -#### Get List of Languages[edit] +## Languages +### Languages +#### Get List of Languages ```bash curl -X GET /api/index.php/v1/languages ``` -#### Install Language[edit] +#### Install Language ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages -d ``` @@ -440,20 +443,20 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages -d "package": "pkg_fr-FR" } ``` -### Content Languages[edit] -#### Get List of Content Languages[edit] +### Content Languages +#### Get List of Content Languages ```bash curl -X GET /api/index.php/v1/languages/content ``` -#### Get Single Content Language[edit] +#### Get Single Content Language ```bash curl -X GET /api/index.php/v1/v1/languages/content/{language_id} ``` -#### Delete Content Language[edit] +#### Delete Content Language ```bash curl -X DELETE /api/index.php/v1/languages/content/{language_id} ``` -#### Create Content Language[edit] +#### Create Content Language ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/content -d ``` @@ -473,7 +476,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/con "title_native": "Français (France)" } ``` -#### Update Content Language[edit] +#### Update Content Language ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/content/{language_id} -d ``` @@ -488,20 +491,20 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/co "title_native": "English (United Kingdom)" } ``` -### Overrides Languages[edit] -#### Get List of Overrides Languages Constants[edit] +### Overrides Languages +#### Get List of Overrides Languages Constants ```bash curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code} ``` -#### Get Single Override Language Constant[edit] +#### Get Single Override Language Constant ```bash curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} ``` -#### Delete Content Language[edit] +#### Delete Content Language ```bash curl -X DELETE /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} ``` -#### Create Content Language[edit] +#### Create Content Language ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code} -d ``` @@ -511,7 +514,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/ove "override": "text" } ``` -#### Update Content Language[edit] +#### Update Content Language ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} -d ``` @@ -524,7 +527,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/ov - var app - enum {"site", "administrator"} - var lang_code - string Example: “fr-FR“, “en-GB“ you can get lang_code from v1/languages/content -#### Search Override Constant[edit] +#### Search Override Constant ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/search -d ``` @@ -535,26 +538,26 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/ove } ``` - var searchtype - enum {“constant”, “value”}. “constant” search by constant name, “value” - search by constant value -#### Refresh Override Search Cache[edit] +#### Refresh Override Search Cache ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/search/cache/refresh ``` -## Menus[edit] -### Menus[edit] -#### Get List of Menus[edit] +## Menus +### Menus +#### Get List of Menus ```bash curl -X GET /api/index.php/v1/menus/{app} ``` -#### Get Single Menu[edit] +#### Get Single Menu ```bash curl -X GET /api/index.php/v1/menus/{app}/{menu_id} ``` -#### Delete Menu[edit] +#### Delete Menu ```bash curl -X DELETE /api/index.php/v1/menus/{app}/{menu_id} ``` -#### Create Menu[edit] +#### Create Menu ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app} -d ``` @@ -566,7 +569,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app} - "title": "Menu" } ``` -#### Update Menu[edit] +#### Update Menu ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/{menu_id} -d ``` @@ -576,24 +579,24 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/ "title": "New Menu" } ``` -### Menus Items[edit] -#### Get List of Menus Items Types[edit] +### Menus Items +#### Get List of Menus Items Types ```bash curl -X GET /api/index.php/v1/menus/{app}/items/types ``` -#### Get List of Menus Items[edit] +#### Get List of Menus Items ```bash curl -X GET /api/index.php/v1/menus/{app}/items ``` -#### Get Single Menu Item[edit] +#### Get Single Menu Item ```bash curl -X GET /api/index.php/v1/menus/{app}/items/{menu_item_id} ``` -#### Delete Menu Item[edit] +#### Delete Menu Item ```bash curl -X DELETE /api/index.php/v1/menus/{app}/items/{menu_item_id} ``` -#### Create Menu Item[edit] +#### Create Menu Item ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items -d ``` @@ -645,7 +648,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/i ``` - Example for "Create Article Page" -#### Update Menu Item[edit] +#### Update Menu Item ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items/{menu_item_id} -d ``` @@ -662,21 +665,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/ ``` - Example for "Create Article Page" -## Messages[edit] -### Messages[edit] -#### Get List of Messages[edit] +## Messages +### Messages +#### Get List of Messages ```bash curl -X GET /api/index.php/v1/messages ``` -#### Get Single Message[edit] +#### Get Single Message ```bash curl -X GET /api/index.php/v1/messages/{message_id} ``` -#### Delete Message[edit] +#### Delete Message ```bash curl -X DELETE /api/index.php/v1/messages/{message_id} ``` -#### Create Message[edit] +#### Create Message ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/messages -d ``` @@ -689,7 +692,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/messages -d "user_id_to": 772 } ``` -#### Update Message[edit] +#### Update Message ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/{message_id} -d ``` @@ -702,25 +705,25 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/{me } ``` -## Modules[edit] -### Modules[edit] -#### Get List of Modules Types[edit] +## Modules +### Modules +#### Get List of Modules Types ```bash curl -X GET /api/index.php/v1/modules/types/{app} ``` -#### Get List of Modules[edit] +#### Get List of Modules ```bash curl -X GET /api/index.php/v1/modules/{app} ``` -#### Get Single Module[edit] +#### Get Single Module ```bash curl -X GET /api/index.php/v1/modules/{app}/{module_id} ``` -#### Delete Module[edit] +#### Delete Module ```bash curl -X DELETE /api/index.php/v1/modules/{app}/{module_id} ``` -#### Create Module[edit] +#### Create Module ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/{app} -d ``` @@ -760,7 +763,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/{app} ``` - Example for "Articles - Archived" -#### Update Module[edit] +#### Update Module ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/modules/{app}/{module_id} -d ``` @@ -777,21 +780,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/modules/{app ``` - Example for "Articles - Archived" -## Newsfeeds[edit] -### Feeds[edit] -#### Get List of Feeds[edit] +## Newsfeeds +### Feeds +#### Get List of Feeds ```bash curl -X GET /api/index.php/v1/newsfeeds/feeds ``` -#### Get Single Feed[edit] +#### Get Single Feed ```bash curl -X GET /api/index.php/v1/newsfeeds/feeds/{feed_id} ``` -#### Delete Feed[edit] +#### Delete Feed ```bash curl -X DELETE /api/index.php/v1/newsfeeds/feeds/{feed_id} ``` -#### Create Feed[edit] +#### Create Feed ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/feeds -d ``` @@ -837,7 +840,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/fee "published": 1 } ``` -#### Update Feed[edit] +#### Update Feed ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/feeds/{feed_id} -d ``` @@ -853,25 +856,25 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/newsfeeds/fe "name": "Test" } ``` -### Categories[edit] +### Categories - Route Newsfeeds Categories is: "v1/newsfeeds/categories" - Working with it is similar to Banners Categories. -## Privacy[edit] -### Request[edit] -#### Get List of Requests[edit] +## Privacy +### Request +#### Get List of Requests ```bash curl -X GET /api/index.php/v1/privacy/requests ``` -#### Get Single Request[edit] +#### Get Single Request ```bash curl -X GET /api/index.php/v1/privacy/requests/{request_id} ``` -#### Get Single Request Export Data[edit] +#### Get Single Request Export Data ```bash curl -X GET /api/index.php/v1/privacy/request/export/{request_id} ``` -#### Create Request[edit] +#### Create Request ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/privacy/requests -d ``` @@ -881,31 +884,31 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/privacy/reque "request_type":"export" } ``` -### Consent[edit] -#### Get List of Consents[edit] +### Consent +#### Get List of Consents ```bash curl -X GET /api/index.php/v1/privacy/consents ``` -#### Get Single Consent[edit] +#### Get Single Consent ```bash curl -X GET /api/index.php/v1/privacy/consents/{consent_id} ``` -## Redirect[edit] -### Redirect[edit] -#### Get List of Redirects[edit] +## Redirect +### Redirect +#### Get List of Redirects ```bash curl -X GET /api/index.php/v1/redirect ``` -#### Get Single Redirect[edit] +#### Get Single Redirect ```bash curl -X GET /api/index.php/v1/redirect/{redirect_id} ``` -#### Delete Redirect[edit] +#### Delete Redirect ```bash curl -X DELETE /api/index.php/v1/redirect/{redirect_id} ``` -#### Create Redirect[edit] +#### Create Redirect ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/redirect -d ``` @@ -920,7 +923,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/redirect -d "referer": "" } ``` -#### Update Redirect[edit] +#### Update Redirect ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/redirect/{redirect_id} -d ``` @@ -931,21 +934,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/redirect/{re } ``` -## Tags[edit] -### Tags[edit] -#### Get List of Tags[edit] +## Tags +### Tags +#### Get List of Tags ```bash curl -X GET /api/index.php/v1/tags ``` -#### Get Single Tag[edit] +#### Get Single Tag ```bash curl -X GET /api/index.php/v1/tags/{tag_id} ``` -#### Delete Tag[edit] +#### Delete Tag ```bash curl -X DELETE /api/index.php/v1/tags/{tag_id} ``` -#### Create Tag[edit] +#### Create Tag ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/tags -d ``` @@ -963,7 +966,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/tags -d "title": "test" } ``` -#### Update Tag[edit] +#### Update Tag ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/{tag_id} -d ``` @@ -973,21 +976,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/{tag_id "title": "new title" } ``` -## Templates[edit] -### Templates Styles[edit] -#### Get List of Templates Styles[edit] +## Templates +### Templates Styles +#### Get List of Templates Styles ```bash curl -X GET /api/index.php/v1/templates/styles/{app} ``` -#### Get Single Template Style[edit] +#### Get Single Template Style ```bash curl -X GET /api/index.php/v1/templates/styles/{app}/{template_style_id} ``` -#### Delete Template Style[edit] +#### Delete Template Style ```bash curl -X DELETE /api/index.php/v1/templates/styles/{app}/{template_style_id} ``` -#### Create Template Style[edit] +#### Create Template Style ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app} -d ``` @@ -1004,7 +1007,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/sty "title": "cassiopeia - Some Text" } ``` -#### Update Template Style[edit] +#### Update Template Style ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app}/{template_style_id} -d ``` @@ -1015,21 +1018,21 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/templates/st } ``` -## Users[edit] -### Users[edit] -#### Get List of Users[edit] +## Users +### Users +#### Get List of Users ```bash curl -X GET /api/index.php/v1/users ``` -#### Get Single User[edit] +#### Get Single User ```bash curl -X GET /api/index.php/v1/users/{user_id} ``` -#### Delete User[edit] +#### Delete User ```bash curl -X DELETE /api/index.php/v1/users/{user_id} ``` -#### Create User[edit] +#### Create User ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/users -d ``` @@ -1061,7 +1064,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/users -d "username": "ad" } ``` -#### Update User[edit] +#### Update User ```bash curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/users/{user_id} -d ``` @@ -1075,9 +1078,9 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/users/{user_ "username": "username" } ``` -### Fields Users[edit] +### Fields Users - Route Fields Users is: v1/fields/users - Working with it is similar to Fields Contact. -### Groups Fields Users[edit] +### Groups Fields Users - Route Groups Fields Users is: v1/fields/groups/users - Working with it is similar to Groups Fields Contact. \ No newline at end of file From 9992af007a8360eec9be8601280b36dc1c9646cf Mon Sep 17 00:00:00 2001 From: pe7er Date: Tue, 4 Jun 2024 14:35:59 +0200 Subject: [PATCH 3/4] escaped or replaced quotes --- .../webservices/webservices-core-endpoints.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/general-concepts/webservices/webservices-core-endpoints.md b/docs/general-concepts/webservices/webservices-core-endpoints.md index 632743f4..98920274 100644 --- a/docs/general-concepts/webservices/webservices-core-endpoints.md +++ b/docs/general-concepts/webservices/webservices-core-endpoints.md @@ -169,7 +169,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/config/appli ```bash curl -X GET /api/index.php/v1/config/{component_name} ``` -Example “component_name” is “com_content”. +Example ``component_name`` is ``com_content``. #### Update Application Config ```bash @@ -525,7 +525,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/ov } ``` - var app - enum {"site", "administrator"} -- var lang_code - string Example: “fr-FR“, “en-GB“ you can get lang_code from v1/languages/content +- var lang_code - string Example: ``"fr-FR"``, ``"en-GB"`` you can get lang_code from v1/languages/content #### Search Override Constant ```bash @@ -537,7 +537,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/ove "searchtype": "constant" } ``` -- var searchtype - enum {“constant”, “value”}. “constant” search by constant name, “value” - search by constant value +- var searchtype - enum ``{"constant", "value"}``. ``constant`` search by constant name, ``value`` - search by constant value #### Refresh Override Search Cache ```bash curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/search/cache/refresh From a65269de13fe62bca978a1a57b4cef9f42f9d841 Mon Sep 17 00:00:00 2001 From: Harald Leithner Date: Wed, 5 Jun 2024 10:05:03 +0200 Subject: [PATCH 4/4] Escape MDX variables --- .../webservices/webservices-core-endpoints.md | 98 +++++++++---------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/docs/general-concepts/webservices/webservices-core-endpoints.md b/docs/general-concepts/webservices/webservices-core-endpoints.md index 98920274..bdf89886 100644 --- a/docs/general-concepts/webservices/webservices-core-endpoints.md +++ b/docs/general-concepts/webservices/webservices-core-endpoints.md @@ -309,11 +309,11 @@ curl -X GET /api/index.php/v1/fields/groups/contacts/contact ``` #### Get Single Group Fields Contact ```bash -curl -X GET /api/index.php/v1/fields/groups/contacts/contact/{group_id} +curl -X GET /api/index.php/v1/fields/groups/contacts/contact/\{group_id\} ``` #### Delete Group Fields Contact ```bash -curl -X DELETE /api/index.php/v1/fields/groups/contacts/contact/{group_id} +curl -X DELETE /api/index.php/v1/fields/groups/contacts/contact/\{group_id\} ``` #### Create Group Fields Contact ```bash @@ -352,7 +352,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/fields/groups ``` #### Update Group Fields Contact ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact/{group_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/groups/contacts/contact/\{group_id\} -d ``` ```json { @@ -368,7 +368,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/fields/group - Route Group Fields Contact Categories is: "v1/fields/groups/contacts/categories" - Working with it is similar to Group Fields Contact. ### Content History -- Route Content History is: "v1/contacts/{groupid}/contenthistory" +- Route Content History is: "v1/contacts/\{groupid\}/contenthistory" - Working with it is similar to Banners Content History. ## Content @@ -379,11 +379,11 @@ curl -X GET /api/index.php/v1/content/articles ``` #### Get Single Article ```bash -curl -X GET /api/index.php/v1/content/articles/{article_id} +curl -X GET /api/index.php/v1/content/articles/\{article_id\} ``` #### Delete Article ```bash -curl -X DELETE /api/index.php/v1/content/articles/{article_id} +curl -X DELETE /api/index.php/v1/content/articles/\{article_id\} ``` #### Create Article ```bash @@ -404,7 +404,7 @@ Currently the options mentioned here are required properties. However the intent #### Update Article ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/articles/{article_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/articles/\{article_id\} -d ``` ```json { @@ -425,7 +425,7 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/content/arti - Route Fields Categories is: "v1/fields/groups/content/categories" - Working with it is similar to Fields Contact. ### Content History -- Route Content History is: "v1/content/articles/{article_id}/contenthistory" +- Route Content History is: "v1/content/articles/\{article_id\}/contenthistory" - Working with it is similar to Banners Content History. ## Languages @@ -450,11 +450,11 @@ curl -X GET /api/index.php/v1/languages/content ``` #### Get Single Content Language ```bash -curl -X GET /api/index.php/v1/v1/languages/content/{language_id} +curl -X GET /api/index.php/v1/v1/languages/content/\{language_id\} ``` #### Delete Content Language ```bash -curl -X DELETE /api/index.php/v1/languages/content/{language_id} +curl -X DELETE /api/index.php/v1/languages/content/\{language_id\} ``` #### Create Content Language ```bash @@ -478,7 +478,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/con ``` #### Update Content Language ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/content/{language_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/content/\{language_id\} -d ``` ```json { @@ -494,19 +494,19 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/co ### Overrides Languages #### Get List of Overrides Languages Constants ```bash -curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code} +curl -X GET /api/index.php/v1/languages/overrides/\{app\}/\{lang_code\} ``` #### Get Single Override Language Constant ```bash -curl -X GET /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} +curl -X GET /api/index.php/v1/languages/overrides/\{app\}/\{lang_code\}/\{constant_id\} ``` #### Delete Content Language ```bash -curl -X DELETE /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} +curl -X DELETE /api/index.php/v1/languages/overrides/\{app\}/\{lang_code\}/\{constant_id\} ``` #### Create Content Language ```bash -curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code} -d +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/\{app\}/\{lang_code\} -d ``` ```json { @@ -516,7 +516,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/ove ``` #### Update Content Language ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/{app}/{lang_code}/{constant_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/languages/overrides/\{app\}/\{lang_code\}/\{constant_id\} -d ``` ```json { @@ -547,19 +547,19 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/languages/ove ### Menus #### Get List of Menus ```bash -curl -X GET /api/index.php/v1/menus/{app} +curl -X GET /api/index.php/v1/menus/\{app\} ``` #### Get Single Menu ```bash -curl -X GET /api/index.php/v1/menus/{app}/{menu_id} +curl -X GET /api/index.php/v1/menus/\{app\}/\{menu_id\} ``` #### Delete Menu ```bash -curl -X DELETE /api/index.php/v1/menus/{app}/{menu_id} +curl -X DELETE /api/index.php/v1/menus/\{app\}/\{menu_id\} ``` #### Create Menu ```bash -curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app} -d +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/\{app\} -d ``` ```json { @@ -571,7 +571,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app} - ``` #### Update Menu ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/{menu_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/\{app\}/\{menu_id\} -d ``` ```json { @@ -582,23 +582,23 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/ ### Menus Items #### Get List of Menus Items Types ```bash -curl -X GET /api/index.php/v1/menus/{app}/items/types +curl -X GET /api/index.php/v1/menus/\{app\}/items/types ``` #### Get List of Menus Items ```bash -curl -X GET /api/index.php/v1/menus/{app}/items +curl -X GET /api/index.php/v1/menus/\{app\}/items ``` #### Get Single Menu Item ```bash -curl -X GET /api/index.php/v1/menus/{app}/items/{menu_item_id} +curl -X GET /api/index.php/v1/menus/\{app\}/items/\{menu_item_id\} ``` #### Delete Menu Item ```bash -curl -X DELETE /api/index.php/v1/menus/{app}/items/{menu_item_id} +curl -X DELETE /api/index.php/v1/menus/\{app\}/items/\{menu_item_id\} ``` #### Create Menu Item ```bash -curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items -d +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/\{app\}/items -d ``` ```json { @@ -650,7 +650,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/i #### Update Menu Item ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/{app}/items/{menu_item_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/menus/\{app\}/items/\{menu_item_id\} -d ``` ```json { @@ -673,11 +673,11 @@ curl -X GET /api/index.php/v1/messages ``` #### Get Single Message ```bash -curl -X GET /api/index.php/v1/messages/{message_id} +curl -X GET /api/index.php/v1/messages/\{message_id\} ``` #### Delete Message ```bash -curl -X DELETE /api/index.php/v1/messages/{message_id} +curl -X DELETE /api/index.php/v1/messages/\{message_id\} ``` #### Create Message ```bash @@ -694,7 +694,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/messages -d ``` #### Update Message ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/{message_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/\{message_id\} -d ``` ```json { @@ -709,23 +709,23 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/messages/{me ### Modules #### Get List of Modules Types ```bash -curl -X GET /api/index.php/v1/modules/types/{app} +curl -X GET /api/index.php/v1/modules/types/\{app\} ``` #### Get List of Modules ```bash -curl -X GET /api/index.php/v1/modules/{app} +curl -X GET /api/index.php/v1/modules/\{app\} ``` #### Get Single Module ```bash -curl -X GET /api/index.php/v1/modules/{app}/{module_id} +curl -X GET /api/index.php/v1/modules/\{app\}/\{module_id\} ``` #### Delete Module ```bash -curl -X DELETE /api/index.php/v1/modules/{app}/{module_id} +curl -X DELETE /api/index.php/v1/modules/\{app\}/\{module_id\} ``` #### Create Module ```bash -curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/{app} -d +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/\{app\} -d ``` ```json { @@ -765,7 +765,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/modules/{app} #### Update Module ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/modules/{app}/{module_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/modules/\{app\}/\{module_id\} -d ``` ```json { @@ -868,11 +868,11 @@ curl -X GET /api/index.php/v1/privacy/requests ``` #### Get Single Request ```bash -curl -X GET /api/index.php/v1/privacy/requests/{request_id} +curl -X GET /api/index.php/v1/privacy/requests/\{request_id\} ``` #### Get Single Request Export Data ```bash -curl -X GET /api/index.php/v1/privacy/request/export/{request_id} +curl -X GET /api/index.php/v1/privacy/request/export/\{request_id\} ``` #### Create Request ```bash @@ -902,11 +902,11 @@ curl -X GET /api/index.php/v1/redirect ``` #### Get Single Redirect ```bash -curl -X GET /api/index.php/v1/redirect/{redirect_id} +curl -X GET /api/index.php/v1/redirect/\{redirect_id\} ``` #### Delete Redirect ```bash -curl -X DELETE /api/index.php/v1/redirect/{redirect_id} +curl -X DELETE /api/index.php/v1/redirect/\{redirect_id\} ``` #### Create Redirect ```bash @@ -925,7 +925,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/redirect -d ``` #### Update Redirect ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/redirect/{redirect_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/redirect/\{redirect_id\} -d ``` ```json { @@ -942,11 +942,11 @@ curl -X GET /api/index.php/v1/tags ``` #### Get Single Tag ```bash -curl -X GET /api/index.php/v1/tags/{tag_id} +curl -X GET /api/index.php/v1/tags/\{tag_id\} ``` #### Delete Tag ```bash -curl -X DELETE /api/index.php/v1/tags/{tag_id} +curl -X DELETE /api/index.php/v1/tags/\{tag_id\} ``` #### Create Tag ```bash @@ -968,7 +968,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/tags -d ``` #### Update Tag ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/{tag_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/\{tag_id\} -d ``` ```json { @@ -980,19 +980,19 @@ curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/tags/{tag_id ### Templates Styles #### Get List of Templates Styles ```bash -curl -X GET /api/index.php/v1/templates/styles/{app} +curl -X GET /api/index.php/v1/templates/styles/\{app\} ``` #### Get Single Template Style ```bash -curl -X GET /api/index.php/v1/templates/styles/{app}/{template_style_id} +curl -X GET /api/index.php/v1/templates/styles/\{app\}/\{template_style_id\} ``` #### Delete Template Style ```bash -curl -X DELETE /api/index.php/v1/templates/styles/{app}/{template_style_id} +curl -X DELETE /api/index.php/v1/templates/styles/\{app\}/\{template_style_id\} ``` #### Create Template Style ```bash -curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app} -d +curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/styles/\{app\} -d ``` ```json { @@ -1009,7 +1009,7 @@ curl -X POST -H "Content-Type: application/json" /api/index.php/v1/templates/sty ``` #### Update Template Style ```bash -curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/templates/styles/{app}/{template_style_id} -d +curl -X PATCH -H "Content-Type: application/json" /api/index.php/v1/templates/styles/\{app\}/\{template_style_id\} -d ``` ```json {