# How to organize an API using url prefixes... or not to
**URL:** https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036
**Category:** Uncategorized
**Created:** [July 18, 2017, 3:25pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036 "2017-07-18T15:25:29Z")
**Posts on this page:** 5
**Page:** 1
### Author:  [@SierraRomeo](https://discuss.jsonapi.org/u/SierraRomeo)
#### Post date: [July 18, 2017, 3:25pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036/1 "2017-07-18T15:25:29Z")
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?
---
### Author:  [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)
#### Post date: [July 18, 2017, 3:38pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036/2 "2017-07-18T15:38:38Z")
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](http://blog.michaelhibay.com/2017/03/29/development-guidelines-for-hypermedia-apis/) is a good start.
After you’re through the guidelines I have other posts on the topic to help with general information.
---
### Author:  [@OliverSalzburg](https://discuss.jsonapi.org/u/OliverSalzburg)
#### Post date: [July 18, 2017, 3:50pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036/3 "2017-07-18T15:50:39Z")
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.
---
### Author:  [@SierraRomeo](https://discuss.jsonapi.org/u/SierraRomeo)
#### Post date: [July 18, 2017, 3:57pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036/4 "2017-07-18T15:57:41Z")
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.
---
### Author:  [@michaelhibay](https://discuss.jsonapi.org/u/michaelhibay)
#### Post date: [July 18, 2017, 4:11pm UTC](https://discuss.jsonapi.org/t/how-to-organize-an-api-using-url-prefixes-or-not-to/1036/5 "2017-07-18T16:11:40Z")
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.
> [@OliverSalzburg](#):
>
> 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.
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.