1

I'm in the process of designing the API layer of one of the research and development applications my company is building. The purpose of the API is to share data from a database and to provide calculation functionalities on our data.

My idea is to build Controller endpoints that follow the classic pattern resources nouns and rest verbs:

GET /api/v1/{organisations}
GET /api/v1/{organisations}/{id}
GET /api/v1/{organisations}/{id}/{offices}

etc.

The developer who's handing me the project strongly suggested that I don't use this convention, he said that companies are moving away from this convention as it is too verbose and, hence, not efficient.

He is suggesting adopting less structured endpoints. Something like this, from the code:

GET /api/v1/{taxEnvId}/covers 
GET /api/v1/{coverId}/occupclasses

for example, where the first url could be anything.

I objected saying that it shouldn't change much in terms of efficiency and that the advantages in terms of self-documentation with the design I'm suggesting would be greater than the (in my opinion) very small inefficiency (in terms of bytes sent per request) introduced by a longer path.

He is much more experienced than I am, so I'm wondering whether I am making a mistake in my current 'design'.

Is the classic verb - nouns rest name convention wrong? Are there any disadvantages I can't see in using that convention? Is he right stressing on that convention being inefficient?

I couldn't find anyone complaining about that convention on the internet and I'd be happy to listen to other opinions or even redirection to books and links that make my evaluation of this part of the design better.

Jimmy
  • 101
  • 1
  • 1
  • 7
  • I don't see any advantages to his design. Why would the ID be before the description of what that ID represents? That's entirely unintuitive to me. Can he describe the "efficiency" gains of this design? Because I'm not seeing them by the URLs alone. – David Aug 26 '17 at 00:27
  • Not to derail your ideas, but I hear GraphQL is the next REST – OneCricketeer Aug 26 '17 at 00:44
  • Anyways, regarding the suggested option. I would think that `/covers?id={taxEnvId}` would be "more efficient" – OneCricketeer Aug 26 '17 at 00:47
  • Is this question really targeted towards REST or just the buzzword for any HTTP API? In the primer case the structure of the URL isn't important at all, what is important is the relation name you give the URI, this is what RESTful clients will use in order to decide whether to invoke it or not. Also, REST is probably the wrong architecture to use if minimizing the data payload is of upmost priority as all the metadata and links you have to add in the response as well as the back and forth negotiations and options check on every URI can make up for a bit of additional overhead in general. – Roman Vottner Aug 26 '17 at 09:12

3 Answers3

0

IMHO your approach seems cleaner and more understandable. An API must be intuitive and easy to use.

Some links that may work for you:

javiergarval
  • 348
  • 3
  • 14
0

I objected saying that it shouldn't change much in terms of efficiency

Since the change is not that different then is it worth arguing over? If he is a senior engineer and the organization wants to try a smaller path approach, then this is an opportunity to help the organization accomplish this goal. If in the end their change to less verbose URL paths leads to no improvement, you can rest assured that you helped arrive to that conclusion. You gotta pick your battles and both URL's look very similar, not really worth arguing if in the end of the day it comes down to opinion, especially when the team already expressed an interest to make the URL paths less verbose.

Jose Martinez
  • 11,452
  • 7
  • 53
  • 68
0

If you (the company) provides not just data but also functionality in your API, then Rest is a good way to go. Otherwise GraphQL could be a thing, both are fundamentally different. In short: GraphQL shines if you don't offer buisiness logic.

What I would argue about your approach is the /v1, because that isn't a resource. Versioning is topic on its own.

I find it not very efficient adopting this:

GET /api/v1/{taxEnvId}/covers 
GET /api/v1/{coverId}/occupclasses

Just imagine the backing controller. The more types the API has, the more cluttered this controller will become. If that happens, how could this be more efficient or efficient at all? The urls are short, but urls are cheap. If he is arguing on bytes being send, introduce him to gzip-compression.

sschrass
  • 7,014
  • 6
  • 43
  • 62