0

I am writing huge Rest API, to make it easily discoverable, i am making the pattern like this way.

http://127.0.0.1:8000/membership/api/v1/make-a-payment

But i notice poeple used to make the pattern like this way: http://127.0.0.1:8000/ap/v1/blabla

Can you anyone tell me what is the best practice?

is it ok writing pattern like this way? http://127.0.0.1:8000/membership/api/v1/make-a-payment ?

I just trying to make it easily discoverable by swegger docs.

What is your opinion?

1 Answers1

1

Can you anyone tell me what is the best practice?

REST doesn't care what spelling conventions you use for your resource identifiers.

RFC 3986 defines paths and path segments.

The path component contains data, usually organized in hierarchical form...

Many will therefore choose to align their identifier hierarchy with the hierarchy of their resources. It's not required that you do so, but as an organizing principle it's not bad, and of course no worse than any other arbitrarily selected convention.

For example, a common practice is that collection items will have identifier spellings subordinate to the identifier of the collection itself.

/photos     <-- the collection
/photos/17  <-- an item in the collection

So you might reasonably ask whether api is one item of several in a membership collection, or if membership is one item of several in an api collection.

You might also want to review relative resolution and how dot-segments can be used to navigate up the hierarchy. If references between memberships and some other idea are more common than references between api and some other idea, then the spelling /api/membership may prove to be the more convenient choice.

I think a good guideline is this: any path segment implies the existence of siblings at the same hierarchical level. /membership/api implies the existence of /membership/something-that-isnt-api -- otherwise, why not just /membership ?

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • This is a reasonable answer so I don't want to counter it with a new one. Other alternative path styles are `photo/17` and `photo/list`. Since discovery was mentioned, it highlights the issues with versioning by URL segment yet again, which is the least RESTful method because it violates the _Uniform Interface Constraint_. The path in the URL _is_ the identifier. `v1/photo/17` and `v2/photo/17` implies different resources, when the difference is only _representation_. It also makes discovery harder. Without the version in the path, discovery can be achieved with `OPTIONS /photo` – Chris Martinez Mar 27 '21 at 06:54