Hacker News Reader

Comment by mythz | Hacker News Reader

Funny that Microsoft uses OData as an example of a bad URL:

https://github.com/Microsoft/api-guidelines/blob/master/Guid...

Whilst continuing to praise OData as "the best way to REST" - http://www.odata.org

Microsoft came up with OData about 10 years ago, but it's now steered by a technical committee with a lot of participants. I wouldn't necessarily be so quick to assume that the OASIS committee - or Microsoft's representatives on it - speak for all of Microsoft. Let alone an internal guidelines committee that they apparently convened fairly recently (given the age of the report) when they use that slogan.

This isn't just some poorly labelled content from a 10 year old legacy website from a time before they knew any better, the OData website got a recent redesign sporting new Stock photos and even larger font for their disingenuous labeling which still continue to push OData crapware under the REST banner to fool devs/CIO's into thinking if they adopt OData they're taking advantage of the best form of REST - which is in-contrast and devalues sincere efforts like this where they're actually looking to promote good HTTP API practices.

I recently had the misfortune to have to tackle oData to talk to Dynamics CRM. The choice was between that and SOAP so it was the lesser of two evils.

But compared to the other nice, modern REST API's I'm used it smelt of mould and enterprisey cobwebs. I'd have preferred an old school RPC API over that. At least API's that abuse REST from that direction tend to have the virtue of simplicity.

For that matter, I know it's "bad" to use RPC, but imho it's sometimes the cleanest/simplest interface you can make for something on an API.

You should never have to apologize for delivering value - that's ultimately the purpose of technology. If it's the cleanest/simplest solution to a given requirement, implement it and move on - don't worry about trying to appease cargo cults. Technology should be used as a tool to deliver the best value you can within a given set of requirements. End users don't care how many Internet points from fashionable tech du jour you collect along the way, all that matters to them is the end user experience, invest your energy towards that.

There's nothing wrong with RPC APIs. Other than being "Not Cool" due to the legacy of SOAP, they can deliver some very nice value.

Various RPC mechanisms like Bond and Protocol Buffers (and more recently GRPC) are trying hard to make RPC cool again. Personally, I hope they succeed, as REST (like any technology) doesn't work for everything.

For that matter, communication abstractions over websockets... Which has been most interesting to me in terms of offering some better security choices.

Sure, but is the smell because of OData or is that smell mostly coming from the messy old enterprise cruft that an OData veneer has been applied over? I can't really speak to how Dynamics did this in detail, but on my crusty enterprise platform with a huge existing api surface we did a veneering project as a rest v1 using OData (intentionally avoiding esoteric bits, but using query, $metadata, and limited relationships). It does have an enterprisy cobweb feel in places but I think that'd be present if we'd done it without OData as well.

OData is a big enough tent these days that there are good and bad (relative) bits even inside OData. Fortunately one gets to pick-and-choose what bits you use, so just avoid the bad bits.

The example cited as a bad url makes use of OData functions and parameters, which is definitely a more esoteric part of the spec and has spotty implementation (if at all) amongst OData consumers - so discouraging this kind of API seems perfectly reasonable for a REST-centric guideline.

OTOH the OData query syntax is IMO a lot more reasonable; outside of structured queries built in the form of URI path fragments, if you want to provide a generic query mechanism on top of a store you need some kind of generic query language. $filter is a reasonable such language - it is easy to parse, easy to emit, and relatively easy to read. Yes it has some gaps and a couple bizarre edge cases, but they don't get in the way of mainline consumption scenarios - and it's hard to beat being able to provide a reasonable REST API that clients can construct queries by hand for, and also have these same APIs "just work" when plugged into OData consumers (of which there are quite a few in the enterprise).

No $filter is a horrible construct which accepts a free-form expression that doesn't map cleanly to any variable that's effectively being used as a tunnel to pass an opaque query blob from OData client to an OData server resulting in an anti-pattern violating Microsoft's own Service design guidelines: https://msdn.microsoft.com/en-us/library/ms954638.aspx?f=255...

$filter is an unnatural implementation detail leaking both OData implementation and internal table structures to your user-facing API exposing the entire OData query surface area to consumers where as soon as someone binds to it, your API becomes frozen and your API is forever coupled to the OData server implementation given it's much harder to build a compliant OData query parser than it is to parse a simple HTTP path info and QueryString. So when you need to change your implementation for whatever reason, e.g. you want to populate a part of the query with a search index or alternative NoSql data store, you're headed for a rewrite, whereas if you designed your HTTP API naturally behind an intuitive, impl-agnostic URL structure you could easily change the implementation without breaking your API consumers.

There are a number of examples to cite showing what you say isn't true.

Allowing totally arbitrary OData $filter expressions does lead to problems, but recent versions of OData have a nice mechanism to describe (and discover) what can be filtered on. This is both tooling and developer (for consumption) friendly.

There are many examples of teams providing OData API heads without using SQL as the data store. Teams do this using EXO, various Azure data stores, and custom stores.

Using (for example '$filter=productName eq cupcakes') isn't leaking any weird abstractions, but is giving clients and tooling a nice means to filter a list.

The problem isn't for simple inconsequential queries like: '$filter=productName eq cupcakes' it's as soon as you expose an OData endpoint you're exposing the entire OData query surface area in which you have no idea what complex expressions consumers will decide to execute (unless you are the only consumer), so you're left supporting them all and coupling to the OData server implementation for life. If your API only exposed `?productName=cupcakes` you'd have no such implementation coupling.

Now you're saying you can combat this with recent versions of OData that have filter metadata which is a problem in of itself, additional features, additional metadata services, additional training, additional complexity, etc - making OData an endless rolling spec where eventually every OData client except those developed by Microsoft will fall off the upgrade cliff and no longer see ROI chasing an endless spec. OData's just another big, heavy, tooling-dependent, slow and over-architected, complicated framework - you can avoid it's manufactured problems and create cleaner, faster, more interoperable, more human-friendly and future proofed API's by simply avoiding it in the first place.

The problem with just exposing '?productName=cupcakes' is you're assuming just one filter with simple equality. If you need to expose something even just a little more complex, i.e. "A=1 or B=2", or something other than equality like "A>1" or "B!=2", then you quickly find yourself re-implementing a little expression language, syntax for literals, etc. It is a slippery slope, which one can happily go down and succeed with a custom solution - until you then want someone other than your clients to pull data from. Then they need to build their filter in your language, which is of course different than the next guy's language, and so on and so on.

The fix for this is OData. Not all of OData - just a little bit. It lets one standardize the filter expression syntax (as much of it as you choose to support) without making any requirements on the backend.

I'm personally confident in making the claim that OData $filter doesn't require you to bind to a server implementation, because I work on a service built in Node.js and deployed on Linux in Azure that uses OData as a filter syntax and satisfies it's data requirements from three completely different backend servers, none of which is a SQL Server (not that you mentioned SQL, but it's often cited as "all that OData is good for"). One of them is Elastic Search, BTW :), the other is a proprietary aggregated metrics store, and the third is a cloud-scale columnar data store. All three of these can be queried with the same syntax, from tons of off-the-shelf OData consumers, and for clients the choice of what backend to pull data from is literally the only thing they change. From a business value perspective this is pure win, and this is due in large part to using just a little OData, at just the right spots.

I think of OData like salt in a recipe - a little bit is great; too much ruins the dish. Moderation in all things... :)

You never need to drop down into free form expressions to satisfy a query which should never be exposed over a service boundary, this is a very clear Services anti-pattern introducing unnecessary coupling. Find which requirements your Service needs to implement and expose them under the most intuitive self-descriptive label for end users, if you need Orders after a certain date you can expose `?createdAfter=...` or `createdBefore=...`, `?createdAt=...`, etc.

There's nothing in OData that cannot be done more simply and elegantly without it, if you wan't auto querying check out the approach used in: https://github.com/ServiceStack/ServiceStack/wiki/Auto-Query

It's cleaner, faster, more interoperable and it's implementation is fully substitutable, supporting multiple data sources over a user configurable Surface Area that as it's just the same as any other ServiceStack Service has access to all its existing features it enables for all Services including support for an end-to-end typed API over multiple data formats, that's able to take advantage of existing metadata services, and also includes an optional AutoQuery UI. Because it's just another Service there's also infinitely less incremental knowledge to learn whilst at the same time being able to take advantage of features of existing Services Users already know.

This is just one approach, most people never need the inherent complexity and ridgity in big heavy fx's like OData which used to have traction when MS had all its marketing momentum behind it but it's hey day is over and abandoned by its high profile early adopters, now it just lingers in maintenance-mode, mostly forgotten outside of MS and held on by the few that haven't moved on.

That particular example was chosen not because of OData, but because it required someone to type in a horribly long set of alphanumeric codes.

There's no way a human can effectively type that, nor is there any real way to look at it and figure out what it's doing. That the URL happens to use ODAta (because that's what Exchange does) is not really relevant.

The overriding factor, as called out in the doc, is that URLs should be human understandable. That's not to say canonical id's can't be used, but a big base64 encoded string is not recommended.

Thinking the exact same thing +1

Reply on news.ycombinator.com