Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

pdigital's avatar

How to structure API endpoints for accessing One-to-One relationships

Hi all. I'm building a private API, which will have 2 clients. One frontend app built in Vue and one mobile app. In it I have the following models.

User, Shop, Credential. Where:

  • User HasMany Shop
  • Shop HasOne Credential
  • Shop BelongsTo User
  • Credential BelongsTo Shop

The endpoints look like so:

GET/POST shop api/users/{uuid}/shops

GET/PATCH/DELETE shop api/users/{uuid}/shops/{shopUuid}

The thing is that I'm having trouble deciding which endpoint would suit the Credential resource the best. I could use:

GET/PATCH/DELETE credential api/users/{uuid}/shops/{shopUuid}/credentials/{credentialUuid}

However with this endpoint, each time one would like to GET or PATCH a credential, one'd have to provide the uuid and shopUuid. I don't know, that seems a bit like a hassle while one could also just call:

api/credentials/{credentialUuid} (and let middleware and policies further decide whether the authenticated user can access these resources). But I don't know if this correctly follows the RESTful principle.

Does anyone have any experience with structuring API endpoints? Any help would be appreciated.

0 likes
5 replies
tisuchi's avatar

@pdigital In my opinion, both URL structures you mentioned are valid, and the best one will depend on the specifics of your project. If you want to strike a balance, consider the following approach:

  • For listing or creating credentials associated with a shop: api/users/{uuid}/shops/{shopUuid}/credentials
  • For direct operations on a known credential: api/credentials/{credentialUuid}

I personally prefer this api/credentials/{credentialUuid} approach because the key advantage here is simplicity. Besides, can directly access without passing through the user and shop hierarchy. The only downside is that the URL doesn't immediately reflect the hierarchical relationship between users, shops, and credentials. However, in many practical situations, this might not be a significant drawback.

pdigital's avatar

@tisuchi I personally also prefer the second approach due to the same reason. I think in this case neither the end user and the API client may need to know the exact hierarchical relationship between users, shops and credentials. Most important is to understand that a user can only CRUD his own credentials.

I'll do some further investigation and provide this initial answer with my chosen solution later :).

martinbean's avatar

@pdigital You can follow Laravel’s conventions for “singleton” resources. Instead of identifying a credential via its unique identifier, you’d instead just have a /users/{user}/shops/{shop}/credential endpoint for retrieving or updating the “credential” resource for a particular shop.

pdigital's avatar

@martinbean This sounds like a good idea. I can't seem to find this part in the docs. Would you mind sharing that part in the documentation?

Please or to participate in this conversation.