readme

Author: basz

README.md

@@ -6,24 +6,52 @@ PLHW API Client provides means to authenticate clients against with OAuth2 serve
 ## Installation
 
 ```bash
-composer require plhw/hf-api-client:^0.1
+composer require plhw/hf-api-client
 ```
 
-## Usage
 
+
+## Example API calls
+
+Once you have succesfully installed the application, some example scripts are located at. To use them first copy an configuration file to your app root. 
+
+```bash
+cp ./vendor/plhw/hf-api-client/example/.hf-api-client-example.php-dist ./.hf-api-client-example.php
 ```
+
+Open `.hf-api-client-example.php` and configure it with credentials you got from us.
+
+Now to can run the example scripts;
+
+```bash
+php ./vendor/plhw/hf-api-client/example/practicesPos.php
+```
+
+## Usage
+
+To implement usage in your application you can have a look at the example scripts.
+
+```php
 $options = \HF\ApiClient\Options\Options::fromArray(
     [
         'server_uri'    => 'https://api.plhw.nl',
-        'client_id'     => $clientId,
-        'client_secret' => $clientSecret,    
+        'client_id'     => 'id',
+        'client_secret' => 'secret',    
         'scope'         => 'customer_pos',
         'grant_type'    => 'client_credentials',
     ]
 );
 
-$api = \HF\ApiClient\ApiClient::createClient($options, $cache);
+$api = \HF\ApiClient\ApiClient::createClient($options, /* $cache OPTIONAL */);
+```
+
+The above is all that is nessesary to configure, though I recommend you tweak the caching meganism. Currently we use the [zendframework/zend-cache](https://docs.zendframework.com/zend-cache/) component. This might change when v3 is released to use the psr-7 caching FIG standard.
+
+When you have `ApiClient` instance you can use it by calling methods as defined in `/vendor/plhw/hf-api-client/data/v1` on it. Additionally [API documentation](https://api.plhw.nl/docs) can be found here.
 
+for example, search the published practices around a coordinate.
+
+```php
 $results = $api->customer_posAroundCoordinate('52.3629882,4.8593175', 15000, 'insoles');
 
 if ($api->isSuccess()) {
@@ -35,12 +63,17 @@ if ($api->isSuccess()) {
 } else {
     printf("Error (%d): %s\n", $api->getStatusCode(), $result);
 }
-
 ```
 
-see api [documentation](https://api.plhw.nl/docs) for end points.
+## Under the hood
+
+When you call any method on the APIClient instance an access token is requested from our OAuth2 server. This access token is then cached for aditional uses up to the moment it expires or is deleted. It will then get a new access token.
+
+Any calls to our API are now `signed` with that access token and is used by our permission system to determain if you have access or not.
+
+Our API will accept and return json payload with are automaticly (de)encoded.
 
-## ClientCredentialsGrant
+### OAuth2 ClientCredentialsGrant
 
 For machine to machine communication OAuth2 ClientCredentialGrant is appropiate. 
 You must obtain the following information from us.