Generalize similars resources in one route


#1

Hi, we have a resource credit-card-payments and another resource wire-transfer-payments. We want them to be accessible through a general payment endpoint:

POST /payments
PATCH /payments/:id
GET /payments
GET /payments/:id

When creating or updating the resources, we specify the type so the server knows which resource (wire-transfer-payments or credit-card-payments) is dealing with. Also, when fetching all the payments, we get a mixed list of wire-transfer-payments and credit-card-payments, so there’s no problem there either.

The problem comes when fetching a specific payments resource. Where the type of the resource (wire-transfer-payments or a credit-card-payments) be passed so the server can handle it?

We thought of using a query-param like GET /payments/:id?type='credit-card-payments' but it doesn’t feel like the best approach.

What would you recommend?


#2

If you want a canonical URL for each specific resource that does not require a query string, I think you’ll want type-specific collections.

You could use top-level collections specific to the type:

/wire-transfer-payments/:id 
/credit-card-payments/:id 

Alternatively, you could nest these collections beneath /payments:

/payments/wire-transfer-payments/:id 
/payments/credit-card-payments/:id 

Whichever you choose, you should return this URL as a self link whenever fetching a resource. This will help consumers target specific resources which were fetched from your heterogeneous collection endpoint (/payments).


#3

Ok, I’ll handle it with the following routes:

POST /payments/wire-transfer/
POST /payments/credit-card/

PATCH /payments/wire-transfer/:id
PATCH /payments/credit-card/:id

GET /payments/wire-transfer/:id
GET /payments/credit-card/:id

GET /payments

Thanks!