Path Parameters

[constantine2nd]

Path parameters are variable parts of a URL path. They are typically used to point to a specific resource within a collection, such as a user identified by ID. For instance: /users/{userId}

OBP-API uses next notation: /users/USER_ID

We need to consider using curly braces i.e {userId} instead of USER_ID in documentation.

[constantine2nd]

Related issues: #692, #693, #694, #696, #697

[chrisjsimpson]

Yes. The motivation here is clarity of variable parts of the api call vs paths. It's pretty standard convention by now to refer to variable parts with brackets. Some examples:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.14/#binding-v1-core

Giant swarm: https://docs.giantswarm.io/api/#operation/createUser

Without this it can be confusing for developers seeing the api for the first time. e.g. for Open Bank Project's Grant User Access View:

The api call is confusing because it's not obvious which parts the developer may change. /obp/v3.1.0/banks/BANK_ID/accounts/ACCOUNT_ID/permissions/PROVIDER/PROVIDER_ID/views/VIEW_ID

Compared to much clearer: /obp/v3.1.0/banks/{bankId}/accounts/{accountId}/permissions/{provider}/{providerId}/views/{viewId}

There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. :wink:

Implementing this improvement would impact:

• API Explorer
• Documentation
• OpenAPI Generation At the benefit of :chart_with_upwards_trend: developer experience :smile:

@simonredfern