Added API client

Author: rimi-itk

.gitignore

@@ -1,6 +1,8 @@
-composer.lock
-vendor/
-
 ###> friendsofphp/php-cs-fixer ###
 /.php-cs-fixer.cache
 ###< friendsofphp/php-cs-fixer ###
+
+*.local
+.idea
+composer.lock
+vendor/

README.md

@@ -2,6 +2,42 @@
 
 API client for [The cBrain F2 Platform](https://www.cbrain.com/software-pages/the-f2-platform).
 
+## Installation
+
+``` shell
+composer require itk-dev/f2-api-client
+```
+
+## Testing
+
+Edit `.env.local` and set these variables:
+
+``` dotenv
+# .env.local
+F2_API_URI=
+F2_API_USERNAME=
+F2_API_SECRET=
+F2_F2_USERNAME=
+```
+
+Run
+
+``` shell
+docker compose run --quiet --rm phpfpm php bin/f2-api-client getServiceIndex
+```
+
+to check that you can talk to the F2 API.
+
+Search cases with
+
+``` shell
+docker compose run --quiet --rm phpfpm php bin/f2-api-client searchCases '{"q": "test", "count": 10}'
+```
+
+docker compose run --quiet --env PHP_XDEBUG_MODE=debug --rm phpfpm php bin/f2-api-client
+
+---
+
 ``` mermaid
 ---
 title: F2 Conceptual model
@@ -10,6 +46,11 @@ title: F2 Conceptual model
 classDiagram
     Document --> Matter
     Matter --> CaseFile
+    Party
+    Note --> CaseFile: (only if not related to Matter)
+    Note --> Matter: (only if not related to CaseFile)
+
+    Chat --> Matter
 
     %% class Item{
     %%     +String title
@@ -19,3 +60,8 @@ classDiagram
     %% Item <|-- Matter
     %% Item <|-- CaseFile
 ```
+
+
+> The client MUST read the service index at runtime and use it to locate the links it needs.
+
+<./resources/f2-rest-docs-v13.pdf#page=8>

bin/f2-api-client

@@ -0,0 +1,15 @@
+#!/usr/bin/env php
+<?php
+
+// @see https://getcomposer.org/doc/articles/vendor-binaries.md#finding-the-composer-autoloader-from-a-binary
+require $_composer_autoload_path ?? __DIR__ . '/../vendor/autoload.php';
+
+use Symfony\Component\Console\Application;
+
+$application = new Application('f2-api-client', '1.0.0');
+$command = new \ItkDev\F2ApiClient\Command\F2ApiClientCommand();
+
+$application->addCommand($command);
+
+$application->setDefaultCommand('f2:api:client', true);
+$application->run();

compose.yaml

@@ -9,6 +9,10 @@ services:
             - PHP_IDE_CONFIG=serverName=localhost
         volumes:
             - .:/app
+        # https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#additional-information-1
+        env_file:
+            - path: .env.local
+              required: false
 
     # Code checks tools
     markdownlint:

composer.json

@@ -3,7 +3,13 @@
     "description": "F2 API client",
     "license": "MIT",
     "type": "library",
+    "require": {
+        "symfony/console": "^6.4 || ^7.4",
+        "symfony/http-client": "^6.4 || ^7.4",
+        "symfony/options-resolver": "^6.4 || ^7.4"
+    },
     "require-dev": {
+        "php": "^8.3",
         "ergebnis/composer-normalize": "^2.52",
         "friendsofphp/php-cs-fixer": "^3.95"
     },
@@ -12,6 +18,9 @@
             "ItkDev\\F2ApiClient\\": "src/"
         }
     },
+    "bin": [
+        "bin/f2-api-client"
+    ],
     "config": {
         "allow-plugins": {
             "ergebnis/composer-normalize": true

src/ApiClient.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace ItkDev\F2ApiClient;
+
+use Symfony\Component\HttpClient\HttpClient;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+class ApiClient
+{
+    protected const string METHOD_GET = 'GET';
+    protected const string METHOD_POST = 'POST';
+
+    private readonly array $options;
+    private HttpClientInterface $client;
+
+    public function __construct(
+        array $options,
+    ) {
+        $resolver = new OptionsResolver();
+        $this->configureOptions($resolver);
+
+        $this->options = $resolver->resolve($options);
+    }
+
+    public function getServiceIndex(): array
+    {
+        $path = '/F2Rest/ServiceIndex';
+        $response = $this->request(self::METHOD_GET, $path);
+
+        return $response->toArray();
+    }
+
+    public function searchCases(array $query): array
+    {
+        //        $query = [];
+        $path = '/F2Rest/search/cases';
+        // @todo  /F2Rest/ServiceIndex.json reports
+        //
+        // "http://cbrain.com/casefile/rel/case-search": {
+        //   "href": "/F2Rest/search/cases",
+        //   "title": "Case file search"
+        // },
+        //
+        // but the actual path is /F2Rest/searches/cases!
+        $path = '/F2Rest/searches/cases';
+        $response = $this->request(self::METHOD_GET, $path, [
+            'query' => $query,
+        ]);
+
+        return $response->toArray();
+    }
+
+    /**
+     * @return array{'access_token': string, 'token_type': string}
+     */
+    protected function getAccessToken(): array
+    {
+        // @todo Check existing access token is not expired.
+
+        $client = $this->client();
+        $response = $client->request(self::METHOD_POST, '/F2Rest/oauth2/token', [
+            'auth_basic' => [
+                $this->options['api_username'],
+                $this->options['api_secret'],
+            ],
+            'headers' => [
+                'accept' => 'application/json',
+            ],
+            'body' => [
+                'grant_type' => 'password',
+                'username' => $this->options['f2_username'],
+            ],
+        ]);
+
+        $token = $response->toArray();
+
+        // @todo Store access token.
+
+        return $token;
+    }
+
+    protected function request(string $method, string $path, array $options = []): ResponseInterface
+    {
+        $accessToken = $this->getAccessToken();
+
+        $cmd = 'curl --verbose --header "Authorization: Bearer '.$accessToken['access_token'].'" '.escapeshellarg($this->options['api_uri'].$path.'?'.http_build_query($options['query'] ?? []));
+        echo PHP_EOL, PHP_EOL, $cmd, PHP_EOL, PHP_EOL;
+
+        $cmd .= ' --header "Accept: application/json"';
+        echo PHP_EOL, PHP_EOL, $cmd, PHP_EOL, PHP_EOL;
+
+        return $this->client()->request($method, $path, $options + [
+            'auth_bearer' => $accessToken['access_token'],
+        ]);
+    }
+
+    protected function client(): HttpClientInterface
+    {
+        if (!isset($this->client)) {
+            $this->client = HttpClient::create([
+                'base_uri' => $this->options['api_uri'],
+            ]);
+        }
+
+        return $this->client;
+    }
+
+    protected function configureOptions(OptionsResolver $resolver): void
+    {
+        $resolver->setRequired([
+            'api_uri',
+            'api_username',
+            'api_secret',
+            'f2_username',
+        ]);
+    }
+}

src/Command/F2ApiClientCommand.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace ItkDev\F2ApiClient\Command;
+
+use ItkDev\F2ApiClient\ApiClient;
+use Symfony\Component\Console\Attribute\Argument;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Exception\InvalidArgumentException;
+use Symfony\Component\Console\Exception\RuntimeException;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+#[AsCommand(name: 'f2:api:client')]
+class F2ApiClientCommand
+{
+    private ApiClient $client;
+
+    public function __invoke(
+        SymfonyStyle $io,
+        #[Argument]
+        string $action,
+        #[Argument]
+        ?string $arg = null,
+    ): int {
+        $client = $this->createClient();
+        if (!method_exists($client, $action)) {
+            throw new InvalidArgumentException('Invalid action: '.$action);
+        }
+
+        if (null !== $arg) {
+            $arg = json_decode($arg, true);
+        }
+        $response = $client->{$action}($arg);
+
+        $io->writeln(json_encode($response, JSON_PRETTY_PRINT));
+
+        return Command::SUCCESS;
+    }
+
+    private function createClient(): ApiClient
+    {
+        if (!isset($this->client)) {
+            $getEnv = static function (string $name): string {
+                $value = getenv($name);
+                if (false === $value || empty($value)) {
+                    throw new RuntimeException(sprintf('Cannot read environment variable %s', $name));
+                }
+
+                return $value;
+            };
+
+            $config = [
+                'api_uri' => $getEnv('F2_API_URI'),
+                'api_username' => $getEnv('F2_API_USERNAME'),
+                'api_secret' => $getEnv('F2_API_SECRET'),
+                'f2_username' => $getEnv('F2_F2_USERNAME'),
+            ];
+
+            $config = array_filter($config);
+            if (4 !== count($config)) {
+                throw new RuntimeException();
+            }
+
+            $this->client = new ApiClient($config);
+        }
+
+        return $this->client;
+    }
+}