Skip to content

Commit 3165def

Browse files
committed
add docs about mid-level und low-level API
1 parent 5316ab6 commit 3165def

File tree

2 files changed

+103
-21
lines changed

2 files changed

+103
-21
lines changed

README.md

Lines changed: 2 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -15,26 +15,8 @@ Uses [Redmine API](http://www.redmine.org/projects/redmine/wiki/Rest_api/).
1515
* Choose between using native `cURL` function or any
1616
[PSR-18](https://www.php-fig.org/psr/psr-18/) http client like
1717
[Guzzle](https://github.com/guzzle/guzzle) for handling http connections
18-
* API entry points implementation state:
19-
* :heavy_check_mark: Attachments
20-
* :heavy_check_mark: Groups
21-
* :heavy_check_mark: Custom Fields
22-
* :heavy_check_mark: Issues
23-
* :heavy_check_mark: Issue Categories
24-
* :heavy_check_mark: Issue Priorities
25-
* :x: *Issue Relations - only partially implemented*
26-
* :heavy_check_mark: Issue Statuses
27-
* :heavy_check_mark: News
28-
* :heavy_check_mark: Projects
29-
* :heavy_check_mark: Project Memberships
30-
* :heavy_check_mark: Queries
31-
* :heavy_check_mark: Roles
32-
* :heavy_check_mark: Time Entries
33-
* :heavy_check_mark: Time Entry Activities
34-
* :heavy_check_mark: Trackers
35-
* :heavy_check_mark: Users
36-
* :heavy_check_mark: Versions
37-
* :heavy_check_mark: Wiki
18+
* [mid-level API](https://github.com/kbsali/php-redmine-api/blob/v2.x/docs/usage.md#mid-level-api) e.g. `$client->getApi('issue')->create($data)`
19+
* [low-level API](https://github.com/kbsali/php-redmine-api/blob/v2.x/docs/usage.md#low-level-api) e.g. `$client->requestPost('/issues.json', $data)`
3820

3921
## Todo
4022

docs/usage.md

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,9 @@ try {
217217

218218
## API
219219

220-
You can now use the `getApi()` method to create and get a specific Redmine API.
220+
### Mid-level API
221+
222+
You can now use the `getApi()` method to create and get a specific Redmine API. This simplifies common use-cases and gives you some features like caching and assigning a user to an issue by username instead of the user ID.
221223

222224
To check for failed requests you can afterwards check the status code via `$client->getLastResponseStatusCode()`.
223225

@@ -553,3 +555,101 @@ Array
553555
// Search
554556
$client->getApi('search')->search('Myproject', ['limit' => 100]);
555557
```
558+
559+
#### API entry points implementation state:
560+
561+
* :heavy_check_mark: Attachments
562+
* :heavy_check_mark: Groups
563+
* :heavy_check_mark: Custom Fields
564+
* :heavy_check_mark: Issues
565+
* :heavy_check_mark: Issue Categories
566+
* :heavy_check_mark: Issue Priorities
567+
* :x: *Issue Relations - only partially implemented*
568+
* :heavy_check_mark: Issue Statuses
569+
* :heavy_check_mark: News
570+
* :heavy_check_mark: Projects
571+
* :heavy_check_mark: Project Memberships
572+
* :heavy_check_mark: Queries
573+
* :heavy_check_mark: Roles
574+
* :heavy_check_mark: Time Entries
575+
* :heavy_check_mark: Time Entry Activities
576+
* :heavy_check_mark: Trackers
577+
* :heavy_check_mark: Users
578+
* :heavy_check_mark: Versions
579+
* :heavy_check_mark: Wiki
580+
581+
If some features are missing in `getApi()` you are welcome to create a PR. Besides, it is always possible to use the low-level API.
582+
583+
### Low-level API
584+
585+
The low-level API allows you to send highly customized requests to the Redmine server.
586+
587+
> :bulb: See the [Redmine REST-API docs](https://www.redmine.org/projects/redmine/wiki/Rest_api) for available endpoints and required parameters.
588+
589+
The client has 4 methods for requests:
590+
591+
- `requestGet()`
592+
- `requestPost()`
593+
- `requestPut()`
594+
- `requestDelete()`
595+
596+
Using this methods you can use every Redmine API endpoint. The following example shows you how to rename a project and add a custom field. To build the XML body you can use the `XmlSerializer`.
597+
598+
```php
599+
$client->requestPut(
600+
'/projects/1.xml',
601+
\Redmine\Serializer\XmlSerializer::createFromArray([
602+
'project' => [
603+
'name' => 'renamed project',
604+
'custom_fields' => [
605+
[
606+
'id' => 123,
607+
'name' => 'cf_name',
608+
'field_format' => 'string',
609+
'value' => [1, 2, 3],
610+
],
611+
],
612+
]
613+
])->getEncoded()
614+
);
615+
```
616+
617+
> :bulb: Use `\Redmine\Serializer\JsonSerializer` if you want to use the JSON endpoint.
618+
619+
Or to fetch data with complex query parameters you can use `requestGet()` with the `PathSerializer`:
620+
621+
```php
622+
$client->requestGet(
623+
\Redmine\Serializer\PathSerializer::create(
624+
'/time_entries.json',
625+
[
626+
'f' => ['spent_on'],
627+
'op' => ['spent_on' => '><'],
628+
'v' => [
629+
'spent_on' => [
630+
'2016-01-18',
631+
'2016-01-22',
632+
],
633+
],
634+
],
635+
)->getPath()
636+
);
637+
```
638+
639+
After the request you can use these 3 methods to work with the response:
640+
641+
- `getLastResponseStatusCode()`
642+
- `getLastResponseContentType()`
643+
- `getLastResponseBody()`
644+
645+
To parse the response body from the last example to an array you can use `XmlSerializer`:
646+
647+
```php
648+
if ($client->getLastResponseStatusCode() === 200) {
649+
$responseAsArray = \Redmine\Serializer\XmlSerializer::createFromString(
650+
$client->getLastResponseBody()
651+
)->getNormalized();
652+
}
653+
```
654+
655+
> :bulb: Use `\Redmine\Serializer\JsonSerializer` if you have send the request as JSON.

0 commit comments

Comments
 (0)