UHF-9239: Update documentation

documentation/api-client.md

@@ -1,22 +1,23 @@
 # API client
 
-Base service for calling HTTP JSON APIs.
+Base service for HTTP JSON APIs.
 
 Features:
- - Simple request caching.
- - Optional response mocking on local environments.
+ - Simple caching.
+ - Optional response mocking for local environment.
+ - Fail any further request instantly after one failed request.
 
 ## Usage
 
-Extend `\Drupal\helfi_api_base\ApiClient\ApiClient`.
+Extend `\Drupal\helfi_api_base\ApiClient\ApiClient`. Requests are made in the callbacks of `cache()` method.
 
 ```php
 namespace Drupal\my_module;
 
-use Drupal\helfi_api_base\ApiClient\ApiClientBase;
+use Drupal\helfi_api_base\ApiClient\ApiClient;
 use Drupal\helfi_api_base\ApiClient\CacheValue;
 
-class MyApi extends ApiClientBase {
+class MyApi extends ApiClient {
 
   const TTL = 180;
 
@@ -31,9 +32,9 @@ class MyApi extends ApiClientBase {
 }
 ```
 
-### Service configuration
+### Service
 
-Extend your service from the abstract service `helfi_api_base.api_client_base`. By default, you must provide your own logger and optional authorization service and default request parameters.
+Extend your service from the abstract service `helfi_api_base.api_client_base`. You must provide your own logger. Optionally you can provide default request parameters and headers.
 
 ```yaml
 # my_module.services.yml
@@ -42,36 +43,23 @@ my_module.my_api:
   class: Drupal\my_module\MyApi
   arguments:
     - '@logger.channel.my_module'
-    - '@my_module.authorization'
     - { timeout: 30 }
 ```
 
-### Adding authorization to requests
-
-Authorization headers can be added create and authorization service. For simple use case, extend the vault authorizer. The authorizer requires name of the vault you are going to use. Pass this service to your client like in the previous example.
-
-```yaml
-# my_module.services.yml
-my_module.authorization:
-  parent: helfi_api_base.vault_authorizer
-  arguments:
-    - 'my_module.vault_key'
-```
-
-### Mocking requests
+### Mocking
 
-If a requests fails, the client can serve mock responses in the local environment. Use `fixture` parameter of the `makeRequest` function.
+In local environment, the `makeRequestWithFixture` method returns response from JSON file if the response fails.
 
 ```php
 class MyApi extends ApiClientBase {
 
-public function getFoo(string $id) {
-  return $this->cache($id, fn () => new CacheValue(
-    $this->makeRequest('GET', 'https://example.com/fail', fixture: '/tmp/fixture.json'),
-    $this->time->getRequestTime() + self::TTL,
-    ['user:1']
-  ))->response;
-}
+  public function getFoo(string $id) {
+    return $this->cache($id, fn () => new CacheValue(
+      $this->makeRequestWithFixture('path-to-fixture.json', 'GET', 'https://example.com/fail'),
+      $this->time->getRequestTime() + self::TTL,
+      ['user:1']
+    ))->response;
+  }
 
 }
 ```