Skip to content

Commit

Permalink
Cleanup readme
Browse files Browse the repository at this point in the history
  • Loading branch information
casperbakker committed Mar 28, 2024
1 parent 524110e commit 06ec7bd
Showing 1 changed file with 0 additions and 24 deletions.
24 changes: 0 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,26 +147,6 @@ Methods on the Client may throw Exceptions. All Exceptions have the parent class
- `RateLimitException` is thrown when the throttling limit has been reached for the API user.
- `Exception` is thrown when an error occurred in the HTTP library that is not covered by the cases above. We aim to map as much as possible to either `ConnectionException` or `ResponseException`.

## Migrate to v10
If you're migrating to v10, please have a look at the official migration guides to find out what has changed:
- [bol.com Retailer API migration guide from v9 to v10](https://api.bol.com/retailer/public/Retailer-API/v10/migrationguide/v9-v10/migrationguide.html)
- [bol.com Retailer API migration guide from v8 to v9](https://api.bol.com/retailer/public/Retailer-API/v9/migrationguide/v8-v9/migrationguide.html)
- [bol.com Retailer API migration guide from v7 to v8](https://api.bol.com/retailer/public/Retailer-API/v8/migrationguide/v7-v8/migrationguide.html)

### Gradual rollout
It's easy to overlook changes when migrating to a new version, which could result in undesired behaviour. You may consider a gradual rollout to minimize impact on your business. You can achieve this by using two versions of the API client in your project and a way to test the new version with a small percentage of requests. To use different versions of this client through Composer, fork this project and use a specific version branch of that new temporary repository as dependency.

For example, if you forked it to `my-namespace/bol-retailer-php-client`, you can add v10 next to your current version with:

```
composer require my-namespace/bol-retailer-php-client "v10.x-dev"
```

You might need to add that temporary repository as [vcs repository in Composer](https://getcomposer.org/doc/05-repositories.md#vcs) for this package to be visible to Composer. When the new version is running stable, remove the old version from your project and delete the fork.

## Version support expectations
As we're require this client in production at Picqer and this will be the case for the foreseeable future, we will make sure that there is always support a version that is either in the GA or Deprecation [lifecycle stage](https://api.bol.com/retailer/public/Retailer-API/release-planning.html) (and not removed). We have thousands of connected partners using many API services and ideally we want to rollout new API versions slowly, so it might happen that we update this library to the latest GA version in the final weeks before removal of the current supported version.

## Contributing
Please follow the guidelines below if you want to contribute.
- Add the latest API specs of the version you want to contribute to and generate the models and client (see: 'Generated Models and Client').
Expand All @@ -176,7 +156,6 @@ Please follow the guidelines below if you want to contribute.
- Rename the namespaces in `/src`, `/tests` and `composer.json`.
- Replace 'v10' with the new version in the test fixtures and in `BaseClient`.
- Update this README with links to the new migration guide(s) and replace 'v10' with the new version.
- Keep in mind that we want to support PHP 7.1 as long as possible.

## Generated Models and Client
The Client and all models are generated by the supplied [Retailer API specifications](https://api.bol.com/retailer/public/apispec/Retailer%20API%20-%20v10) (`src/OpenApi/retailer.json`) and [Shared API specification](https://api.bol.com/retailer/public/apispec/Shared%20API%20-%20v10) (`src/OpenApi/shared.json`). These specifications are merged. Generating the code ensures there are no typos, not every operation needs a test and future (minor) updates to the specifications can easily be applied.
Expand All @@ -197,7 +176,6 @@ The specifications define types for each request and response (if it needs to se

To generate the Client, the following composer script may be used:
```
# Generates Picqer\BolRetailerV10\Client
composer run-script generate-client
```

Expand All @@ -206,7 +184,6 @@ The class names for models are equal to the keys of the array 'definitions' in t

To generate the Models, the following composer script may be used:
```
# Generates all Picqer\BolRetailerV10\Model\* models
composer run-script generate-models
```

Expand All @@ -226,4 +203,3 @@ composer run-script generate-models
```
- Operation 'get-invoices' is specified to have a string as response, while there is clearly some data model returned in JSON or XML.
- The description of the operation 'get-invoices' contains a weird space marked as 'ENSP'.
- If your application is an intermediary, you want to make sure that migrating from the client credentials authentication to the code flow authentication for a certain connection happens for the same Bol.com webshop. There is no endpoint to identify the webshop, but the JWT access tokens do contain the Seller (id). So the suggested method is to compare the Sellers from the old and new access tokens. Keep in mind that the (decoded) content of these access tokens for both authentication methods have different formats. Also, this method should be replaced when Bol.com adds an endpoint to identify the Seller, as the contents of the JWT tokens are undocumented and may change at any point in time. They could even be replaced by non-JWT tokens by Bol.com.

0 comments on commit 06ec7bd

Please sign in to comment.