1

I am building an API that will connect to multiple databases. I am using Emberjs on the front end and the default rest adapter seems to prefer shallow routes. Say, I have the following routes

api/databases
api/databases/1/employees

At this point, my routes are already 2 levels deep. Any further nesting makes it hard to deal with

api/databases/1/employees/2/tasks

In the above URL, I'd like to be able to eliminate the 'databases/1/' portion which will make the rest of the resources easy to access within one or two levels but I am not sure how to pass in the information about the database. I thought about using query parameters but that seems like bad design

api/employees/2/tasks?database=1

Any feedback would be appreciated.

  • Will the same user generally be connecting to more than one database when using the API? Or will the majority of users connect to a single database, but different users will connect to different databases? – LeopardSkinPillBoxHat Jan 22 '16 at 3:05
  • Also, are the IDs used to identify an employee globally unique, or unique within an individual database? – LeopardSkinPillBoxHat Jan 22 '16 at 3:09
  • @LeopardSkinPillBoxHat - About 70% of our users connect to a single database while the rest will connect to more than 1. The ID used to identify an employee is unique only within the database. The only globally unique IDs in the system are the database IDs – user212161 Jan 22 '16 at 3:17
  • 1
    Are you confusing the depth of your routes with the depth of your urls? Can't a top level route include an arbitrarily deep path? – VoiceOfUnreason Jan 22 '16 at 4:15
  • @VoiceOfUnreason - The top level route in this case can change if they want to lookup staff from a different database. It happens quite frequently for the 30% of users engaged in support and administration. – user212161 Jan 22 '16 at 13:16
2

I assume that you will be using some sort of authentication in your API. Let's say (for argument's sake) that you're providing an API key (GUID) to each user that they put into the HTTP header when accessing this API:

GET /employees HTTP/1.1
Host: foobar.com
Accept: application/json
Content-Type: application/json
X-Api-Key: AAAABBBB-CCCC-DDDD-EEEE-FFFFFFFFFFFF

Since 70% of API users will always access the same database, you could provide a 1:1 mapping (in your user database) which maps API keys to databases. The API key then fulfils 2 purposes:

  • Identify and authenticate the user
  • Choose the correct database to use

For the 30% of users who need to access multiple databases, simply provide them with different keys for each database.

What this means:

  • You can take out any references to the database in the URI
  • Database-local IDs (e.g. employee) now become globally unique within the context of a particular API call.

This means you can now provide simpler URIs such as the following:

/employees
/employees/2
/employees/2/tasks
/employees/2/tasks/3
  • I never considered doing it this way but I like your solution the more I think about it. Yes, I will need to change how I handle authentication but your design saves me a couple of database queries for each API call because I no longer need to check to see if the user has permission to access the specified database. All I need to do is perform this check once during login. – user212161 Jan 22 '16 at 13:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy