Improve the overall DX experience

[aurelienbobenrieth]

Hi,

I am experiencing significant inconsistencies and issues while working with the Mollie APIs. These problems appear to stem from discrepancies between the documentation, the API itself, and the client. Here are the main concerns:

1. Inconsistent Property Types:

   • The documentation lists optional properties as X | null, but the API client and actual returned data show them as X | undefined. This difference is crucial for those performing strict payload validation and leads to wasted time and effort.

2. Incorrect Property Requirements:

   • Some properties are marked as mandatory in the documentation but are not actually required by the API. This inconsistency causes confusion and potential errors in implementation.

3. Missing OAuth Requirement Information:

   • On the List Profiles API documentation page, it is not mentioned that an OAuth token is needed to access this endpoint. Attempting to use it with an API key results in the following error:

     This API endpoint is only available with an OAuth access token and cannot be accessed with an API key.

4. Lack of Updates:

   • The API client has not been updated in over six months. Regular updates and maintenance would be greatly appreciated to ensure smooth functionality.

Best regards,

[fjbender]

Hi @aurelienbobenrieth,

Thank you for your honest feedback, and I am sorry the current developer experience is not up to par.

We are currently going through a hot update phase of this package. Additionally, we have just migrated our API documentation to a new technology stack.

I'll leave your first two points for @Pimm and team to look through.

On your third point, I have relayed that to our Docs team. It seems the previous default page header, where we explained which authentication methods are applicable to which endpoint, has not been migrated to the new stack.

We are currently cleaning up a lot of issues and will then release an update of this package.

[aurelienbobenrieth]

There are several issues that are confusing and time-consuming:

1. Missing Error Status 410: The documentation lacks error status 410 for canceled or deleted resources. For example, see Mollie Get Mandate Reference.

2. Soft Delete vs. Hard Delete: It would be helpful to specify which resources undergo soft delete and which undergo hard delete.

I am currently implementing synchronization between Mollie data and our database. During this process, I encountered numerous errors related to non-existent mandates. It appears that when a mandate is revoked, it is hard deleted, which leaves payments referencing mandates that no longer have retrievable data. This behavior doesn't make sense to me.

These changes would greatly improve the usability and reliability of the integration process.

[Pimm]

Thanks for creating this issue, Aurélien!

Inconsistent Property Types: The documentation lists optional properties as X | null, but the API client and actual returned data show them as X | undefined. This difference is crucial for those performing strict payload validation and leads to wasted time and effort.

The documentation over at docs.mollie.com is general documentation, not written for the JavaScript ecosystem specifically. As other languages don't have the undefined vs null distinction, I suspect the Mollians working on the documentation may have not put too much thought into the exact terminology. I'll pick this up with Florian (@fjbender).

Incorrect Property Requirements: Some properties are marked as mandatory in the documentation but are not actually required by the API. This inconsistency causes confusion and potential errors in implementation.

When maintaining this client, we use docs.mollie.com as our source of truth. If you encounter inconsistencies, please report them. That would be greatly appreciated by us and the users of this client.

Missing Error Status 410: The documentation lacks error status 410 for canceled or deleted resources. For example, see Mollie Get Mandate Reference.

Soft Delete vs. Hard Delete: It would be helpful to specify which resources undergo soft delete and which undergo hard delete.

I'll pick these up with Florian as well.

Florian is out of the office this week. Please allow him some time to report back.

[aurelienbobenrieth]

Another issue:

https://docs.mollie.com/reference/list-all-subscriptions

This endpoint definitely does not exist within the Node.js Mollie API client.

[aurelienbobenrieth]

This one is not related to the client itself ; but rather a general question:

• When providing metadata to a subscription, what is the reason for not passing these values to each payment metadata created by that subscription ? It would make the process much easier when it comes to reconciling the data from payment webhooks.

[Pimm]

This endpoint definitely does not exist within the Node.js Mollie API client.

It does:

const subscriptions = mollieClient.subscriptions.iterate();

This one is not related to the client itself ; but rather a general question[.]

I am not involved in the design of the Mollie API. I'll forward your question as well.

[maria-swierblewska]

Hi @aurelienbobenrieth what are you currently passing to subscription metadata that you would like to pass to payments? I can check with our product team if supporting this in their considerations