Implementing the API Client in custom code

Module dependency (.info.yml)

It's recommended to set a dependency to the Immoweb API Client in your custom module.

...
dependencies:
  - ...
  - immoweb_api_client:immoweb_api_client

Dependency injection

You can use the static service function from Drupal, however it's recommended to inject the service directly into your class or service where you need it.

\Drupal::service('immoweb_api_client.classified');

There is also an Oauth service, however for normal uses you don't need to bother with the Oauth service since this is implemented in the Classified service for you.

\Drupal::service('immoweb_api_client.oath');

Available methods

immoweb_api_client.classified

createClassified(array $body);
updateClassified(array $body); // NOTE: See Tip #5
deactivateClassified(string $external_id);
deleteClassified(string $external_id);
getClassified(string $reference_id);
getClassifiedStatus(string $reference_id);

 immoweb_api_client.oath

You will probably never need these requests on their own since the immoweb_api_client.classified service implements these methods. But if there would be a very specific reason for you to request data from these endpoints it is possible.

oauthTokenRequest();
oauthTokenRefreshRequest(string $refresh_token);
getToken();
invalidateTokenInformation();

(Very) Basic usage example

\Drupal::service('immoweb_api_client.classified')->deleteClassified('ABC123456789');

Tips for your implementation

This module just provides you the integrated endpoints with some validation checks. So the real implementation is left open for you to develop. Because we don't know how your Drupal back-end looks (e.g usage of nodes vs custom entities or how your content type is called) we can't develop a general implementation for this. What we can do is give you some pointers on how to set-up the actual implementation.

Tip #1: Build a queue worker on the Drupal side as well

Every call you make to the API will give you a new reference ID because after a small initial validation on the API side, your request is put in a queue before it's processed. With the getClassifiedStatus(string $reference_id) method you can request the status object. This will contain information like when the item was created and last changed, the processing status and any validation changes. Since there is no set time on when the item will be processed on the Immoweb side we suggest you to build a queue worker that pulls the status endpoint on each cron run until the status reaches a "final state".

The status can be one of the following values: PENDING, VALIDATED, REJECTED, CLASSIFIED_PERSISTED, MEDIA_PROCESSING, PROCESSED

PROCESSED and REJECTED can be considered as a final state after which Immoweb will no longer update the status object.

So after you make a request it's recommended to store somewhere the reference ID you got back from the API call.

Tip #2: Keep your datamodel structured

If you are in the development phase of your data model and plan on pushing data to Immoweb, it's a good idea to take into consideration the schema of the object Immoweb expects. This will give you a great insight on how the fields are structured and what type of values Immoweb will be expecting. E.g Don't try to pass a free textfield from Drupal to an enumeration field in Immoweb

Tip #3: Think about the whole flow in the lifecycle of a classified

Try to keep a schema of the whole flow. Because trust us, a flow like this can get complex really quickly. Keep into consideration things like:

• If my property get's unpublished in Drupal, what do I do with the one one Immoweb?
  • Delete it?
  • Unpublish it?
• Updating a property in Drupal should trigger the Update request for Immoweb
• Deleting a property in Drupal should? Delete/Unpublish on Immoweb
• ...

Here is an example flow of how an implementation *could* look when using a node as the property. The node in this example contains a checkbox to indicate if the building needs to be pushed to Immoweb. It also has a field to store the reference ID and a field to store the status of the processing. It also takes into consideration Tip #1 to have a queueworker to update the status field.

Tip #4: Build validation logic and test with all property types you plan on using

We recommend to put as much validation logic in place as possible. Immoweb has not documented their validation logic, but the error list is extremely long. We have bumped into fields that become conditionally required based on the property type you select. Value ranges that change between property types etc etc.

Tip #5: There is (currently) no real update request

There is no update endpoint in the Immoweb API, they treat the create interface as a multi-usage one. Basically they check if you provided a reference that already exists on their side. If that's the case they will update the existing item, otherwise create it. You are not required to send all values when making an update request, only values that have changed + some required fields will be sufficient.

While there is no real update logic at the moment, it might be added in the future, hence we anticipated for that by providing a updateRequest method. In the background it will just call the create endpoint, but this means you can build an easy to understand flow with all of the CRUD operations.