Hi Sam
API Design is a broad topic! There's some good material on the apigee.com website regarding API Design. Some of it is older now, but still quite helpful and relevant. For example, relevant to your question:
https://apigee.com/about/blog/technology/restful-api-design-plural-nouns-and-concrete-names
If you click through there, you can navigate the category of "API Design" on the website and see a bunch more articles. https://apigee.com/about/blog/taglist/restful-api-design
Beyond information on apigee.com, there are other sources that are quite good. I personally like the GoCardless stuff. https://github.com/gocardless/http-api-design But there are others. You can search around.
Regarding your question about where to insert the hyphen... I'm not sure you need hyphens. I would say, try to keep the URL pretty simple and easy to read and navigate. If you have compound words like "customer-inquiry", it suggests that you could simplify or clarify.
Usually, RESTful URLs have a container followed by an identifier of the item in the container. The "container" is the plural noun of the entity you're managing. in your case, it is "debitcards" , so you will want to have a root level url element like "debit cards". If you do only debit cards, consider shortening that to "cards".
Under "cards" you then have the identifier of a particular card. Often this is represented as a simple integer: 7651,7652,7653,7654... but obviously it could be a more complex ID, like a base-62 hash string (eg, a48uD4ekfj), or ... less desirably, a uuid. The uuid works, but it's awfully long. Maybe unnecessarily so.
ok, then we have /cards/7653 to identify a specific card. You can apply PUT/POST/GET/DELETE on that resource. Underneath that base resource, there may be a cascade, a hierarchy of other related objects.
I don't know the relationship between accounts and cards - if it is not 1:1, you may have an ownership / container relationship there. Suppose I can have a single account and then zero or more debit cards. In that case the root object type would be account, and the card would be a child (descendant) . So the URL design would be:
/accounts/387ryfjh
/accounts/387ryfjh/debitcards/7654
And of course you will want your API to respond to PUT/POST/GET/DELETE on both of those kinds of URLs.
You also have another item in your URL named "customer-inquiry". That sounds "verbish" implying an action. In general in the REST model, we try to keep verbs out of the URL path, and use the PUT/POST/GET/DELETE (and maybe PATCH) verbs . if you want a customer inquiry, maybe the customer that owns the account, you could do something like this:
GET /accounts/387ryfjh/customer
That implies "GET me the CUSTOMER associated to ACCOUNT 387ryfjh ."
Your API would probably not respond to POST/PUT/DELETE on that URL. It's inquiry (GET) only.
And the response to that query might include a canonical URL for the customer resource, which might be:
/customer/476j1G
And against that canonical URL, you could support PUT/POST/DELETE.
As to where to insert the version... you could place it as far to the left as possible, eg
/v1/customer/476j1G
...or you could make it "implicit" and use a header. I prefer the latter just because it keeps things cleaner, but there are proponents of either option.
Helpful?
LinkedIn
Twitter
