How to organize an API using url prefixes... or not to

1

I think the specification allows for this, I didn’t see anything going against it, but what I’m looking for is what YOU would do and why. So imagine the following situation:

  • I have a set of generic objects that share the same name but not the same structure. For this example, let’s use a profile object

  • This object doesn’t have the same meaning and/or structure across the RH department and the Logistics department

  • It would make sense to group some objects under the RH or Logistics umbrella to better organize the 100+ objects of the API

Which solution would you use:

  1. same types
  • api/hr/profiles with "type":"profiles"
  • api/logistics/profiles with "type":"profiles"
  1. different types
  • api/hr/profiles with "type":"hr-profiles"
  • api/logistics/profiles with "type":"logistics-profiles"
  1. match types and url
  • api/hr/hr-profiles with "type":"hr-profiles"
  • api/logistics/logistics-profiles with "type":"logistics-profiles"
  1. drop the idea of url prefixes and thus grouping of business related objects
  • api/hr-profiles with "type":"hr-profiles"
  • api/logistics-profiles with "type":"logistics-profiles"

I’m very tempted by option 1, it’s clean, but we have two different Models sharing the same name AND the same type, only not on the same URI. Is it good practice? Do you see a problem with that?

I like option 2 as well. Except for the fact that the type doesn’t match the object name in the URI. Maybe using a dot in the type to hint at a prefixed URL? "type":"hr.profile" ?

Option 3 has too much repetition I think.

If you think the route to go is option 4, what about all the other objects falling under the umbrella HR for example? Should I prefix their type with hr-* to better organize them?

I’d really like to be able to use prefixes in the URL though.

Maybe there is an option 5 I didn’t think about?
What do you think?

2

Option 5, use hypermedia APIs. I’ve written a lot on the subject so I won’t repeat it here, but I think this link is a good start.

After you’re through the guidelines I have other posts on the topic to help with general information.

3

As a side note, if you can, rename your types. If you have two profiles which differ in their schema, it’s bound to confuse consumers of your API and other developers on your team.

Additionally, I found it extremely beneficial to keep the API hierarchy as flat as possible. Something I took away from @michaelhibay’s reading material, which I would also recommend you to read. This would lead me to your option 4.

1 Like
4

So you would prefix all 20 resources that fall under the HR department umbrella for example with "type":"hr-*" ? So to keep some form of organization. Better use long resources name than nested ones is your mantra.

I’ll read @michaelhibay material, but I need some time for this, APIs are not something I do for a living.

5

Fortunately I do ‘do’ APIs for a living, and as part of the community am here to help. Once you have gone through the material, I think you’ll get an understanding of what I mean by using hypermedia APIs and the following response to Oliver.

I would also suggest renaming the resources, but my suggestion would be to have the renamed resources be a result of the output of properly developed domain vocabulary design, not a direct first step. Simply renaming the resources would only cover up the most obvious confusion problem, while leaving the more insidious and difficult to deal with concerns about redundancy across multiple domains. Realistically, the domains should be modeled in a semantically intuitive way, where the redundant or other confusing quirks could be identified before a lot of work has happened, or worse users have started using the system.