2

So I have a dilema here. Trying to build out a RESTful API. Which means I'd like to have resources defined and also require that consumers reference those resources by id.

For example, the typical {resourceName}/{id}?{querystring}

But the way of course a web UI works, for a ecommerce site is that naturally you have SEO-friendly urls.

So there is a mismatch in terms of application specific URLs where we have application context based urls, context here being an ecommerce site using SEO-friendly URLs. They wouldn't have stuff like /id in it 100% of the time. And actually our site doesn't have any ids whatsoever in the web UI's urls.

So when users go from page to page, we might have urls like www.ourdomain.com/cars/local/usa/ca/sunnyvale-cars. And sometimes we're talking about stripping the '-' or other characters out of the more seo friendly urls, after the UI devs send a request to lets say like above a state resource. I'd strip the city name out of 'sunnyvale-cars' if lets say I wanted info on that city so the UI team might send me '/cities?name=sunnyvale-cars' where our API would need to strip out the city name in order to do the query in the backend which to me just doesn't sound like something our API should be doing. It's also coupling our REST API to the web and web conventions...our REST API should be ignorant of any type of delivery mechanism so that our API can be reused for other apps or other APIs in our Business domain.

There might be times where the UI Engineering team, in fact a lot of times they'll only have URLs like this. There is no user action or lets say dropdown list where they can just grab an id. So they can't always request stuff for the next page by sending me a RESTful URI request every time as they may not have ids all the time. In other words, sometimes they'll have to instead request stuff like this: /states?name="ca" to get something related to that state just as a hypothetical example.

So how in the world do you even build a REST API if your UI team is telling you they won't have ids for everything?

PositiveGuy
  • 17,621
  • 26
  • 79
  • 138
  • 2
    Being RESTful or not has nothing to do with how the URLs look, that's an annoyingly persistent myth. – bereal Aug 25 '15 at 14:55
  • yes it does. Urls (the convention of the URIs) define the resources and relationships (HATAEOS). Being able to reference relationships in a consistent way through resources and ids is critical to REST design vs. RPC design of URIs) – PositiveGuy Aug 25 '15 at 17:20
  • Urls define the structure and how you scale out web content for APIs in the backend hence REST plays a huge part in in this in that there are certain defacto conventions most people use to make their urls RESTful vs. a mess. In a RESTful convention all resources have an id. (conquering complexity by dividing content into resources and ids) – PositiveGuy Aug 25 '15 at 17:23
  • 1
    As long as the URI references a resource, not an action, it's fine. URI like `/cars/local/usa/ca` is as RESTful as `/states?name=ca` or `/fsd345oiah`. You can define relationships using any resource-oriented URIs. That's the whole point of HATEOAS. On the other hand, if you rely on the URL structure, it's not HATEOAS, since there are a-priori conventions besides hypermedia. – bereal Aug 25 '15 at 17:27
  • I mean, I see your point, that it's definitely better to have a good and consistent URI structure than not, but with true HATEOAS that can be changed afterwards however you need without affecting the customer code. – bereal Aug 25 '15 at 17:32
  • 1
    On a practical note, you can develop your API whatever way you want, and expose a mapping proxy to please your UI people. – bereal Aug 25 '15 at 17:34
  • @bereal, I prefer not to inject the application specific stuff into our API (the proxy logic that would be needed). I'm looking at it outward-in, not inward-out for providing the mapping. – PositiveGuy Aug 25 '15 at 18:23
  • @bereal, what do you mean by the idea that you can change the HATEAOS, I'm curious. I know what HATEAOS is and starting to include hypermedia but not sure if you can really change it a lot once you start to establish relationships with resources – PositiveGuy Aug 25 '15 at 18:34
  • The idea is that the API has a single entry point and all the remaining client-server conversation happens through client's following the hypermedia links between the resources. If you change the way how URIs are generated, a properly written client won't even notice the difference. I tried to explain that previously in [this answer](http://stackoverflow.com/a/9639345/770830) with a reference to the book. BTW, the other answer there is good, too. – bereal Aug 25 '15 at 18:48

1 Answers1

1

From a REST purist's point of view no URI is inherently more RESTful than another as long as both use identify the resources. At least, I could not find anything about that in the original thesis.

However, if you find some structure fitting the purposes of your API better, you can create a second endpoint exclusively for the needs of your UI team. That endpoint would serve as a proxy and simply map the SEO-friendly structure to your API in possibly generic way.

Or, applications from the outside are just expected to do the rewriting or any app specific mapping-to-REST API "stuff" since it's really app specific in what that mapping looks like anyway, thus keeping the API ignorant of application specific details, domain logic, or even web conventions which the API should not care about or even know about.

PositiveGuy
  • 17,621
  • 26
  • 79
  • 138
bereal
  • 32,519
  • 6
  • 58
  • 104
  • most web teams rewrite the urls to RESTful convention then make the calls to the RESTful APIs. On no team I've been on has this been an issue now that I recall, the web devs simple were told to make sure they send requests in RESTful format, not seo-friendly to our endpionts – PositiveGuy Aug 25 '15 at 18:01
  • Your second item is an option but to me, mapping like this should live in the delivery mechanism, not our API because we'd be binding our API contract by having logic in it to convert stuff for the web and now our API knows about the web and our API needs to be agnostic to any kind of delivery mechanism. Our API should not care HOW the request comes in and shouldn't need to contain mapping logic specific to certain applications. It's their responsibility to format the URI by the interface strategy set fourth by core APIs that the business needs to reuse – PositiveGuy Aug 25 '15 at 18:03
  • @WeDoTDD I feel your pain, and the whole 'SEO' point sounds a bit irrelevant. I think, UI should follow the API, but that looks like a human/communication/process problem to me, not a technical one. – bereal Aug 25 '15 at 18:08
  • yea I guess really I kinda clarified a discussion I forgot I have had in the past when building out APIs, it's just been a while. Usually yea the web team rewrites so we keep the API agnostic and more user friendly to ALL delopers not just the first application that's using the API. It's just up to us to explain the benefits and reasoning for the web team to say "ok it makes sense for use to do that extra work to call our APIs"... – PositiveGuy Aug 25 '15 at 18:18
  • so I'm concluding that the option I'm going with is that external apps rewrite the Uri to communicate to our REST API. Not the other way around because we want not to inject dependencies on apps into our API if we start handling all this mapping logic that also could grow into oblivion that really should reside in each application (the logic to rewrite in order to call our consistent API interface / convention) – PositiveGuy Aug 25 '15 at 18:20
  • I appended another paragraph to your answer if you don't mind which I think then I can mark your reply as the answer...because then you'd have both options in there. – PositiveGuy Aug 25 '15 at 18:22