Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Most RESTful APIs aren't really RESTful

florian-kraemer.net

Post reply on HN
Print view View original

511–520 of 580 posts

Re: Most RESTful APIs aren't really RESTful

#511

Post by agumonkey »

crabmusket wrote: post #459
agumonkey wrote: post #450

Earlier quoted context omitted.

anything I could read to imitate that workflow ?

I haven't written anything up - maybe one day - but our stack is `ts-morph` to get some basic metadata out of our "service definition" typescript files, `ts-json-schema-generator` to go from there to JSON Schema, `quicktype-core` to go to other languages. Schema validation and type generation vary by language. When we need to validate schemas in JS/TS land, we're using `ajv`. Our generation step exports the JSON Sche…

Can't thank you enough. I'm gonna try these and see.

Re: Most RESTful APIs aren't really RESTful

#512

Post by globular-toast »

This seems to mostly boil down to including links rather than just IDs and having the client "just know" how to use those IDs.

Django Rest Framework seems to do this by default. There seems very little reason not to include links over hardcoding URLs in clients. Imagine just being able to restructure your backend and clients just follow along. No complicated migrations etc. I suspect many people just live with crappy backends because it's too difficult to coordinate the rollout of a v2 API.

However, this doesn't cover everything. There's still a ton of "out of band" information shared between client and server. Maybe there's a way to embed Swagger-style docs directly into an API and truly decouple server and client, bit it would seem to take a lot more than just using links over IDs.

Still I think there's nothing to lose by using links over IDs. Just do it on your next API (or use something like DRF that does it for you).

Re: Most RESTful APIs aren't really RESTful

#513

Post by mixedbit »

uzerfcwn wrote: post #414
mixedbit wrote: post #343

Earlier quoted context omitted.

Most web apps today use APIs that return JSON and are called by JavaScript. Can you use REST for such services or does REST require a switch to HTML representation rendered by the server where each interaction returns new HTML page? How such HTML representation can even use PUT and DELETE verbs, as these are available only to JavaScript code? What If I design a system where API calls can be made both from the web and…

> Most web apps today use APIs that return JSON and are called by JavaScript. Can you use REST for such services You kind of could, but it's a bad idea. A core tenet of the REST architecture is that it supports a network of independent servers that provide different services (i.e. webpages) and users can connect to any of them with a generic client (i.e. a web browser). If your mission is to build a specialized API f…

Thanks for the insight. This very well matches my experience from the top comment of this thread. I added discovery related functionality to JSON based API in an attempt to follow REST and didn't see any benefits from the extra work and complexity. Understanding that REST is inherently for HTML (or a similar hypertext based generic client) and it doesn't make sense to try to match it with JSON+JS based API is very refreshing. Even the article that sparkled this discussion gives example of JSON based API with discover related functionality added to it.

Re: Most RESTful APIs aren't really RESTful

#514

Post by motorest »

cyberax wrote: post #505
motorest wrote: post #484

Earlier quoted context omitted.

> Care to list them? From the top of my head, OData. https://www.odata.org/

This is a recent project. REST happened basically in the environment where your choices were CORBA, DCOM, SOAP and other such monstrosities. Of course, REST won handily. We're not in this environment anymore, thankfully, and REST now is getting some well-deserved scrutiny.

> This is a recent project.

OData officially started out in 2007. Roy Fielding's thesis was published in 2000.

Re: Most RESTful APIs aren't really RESTful

#515

Post by troupo »

motorest wrote: post #498
troupo wrote: post #241

Earlier quoted context omitted.

> but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves. Only because we never had the tools and resources that, say, GraphQL has. And now everyone keeps re-inventing half of HTTP anyway. See this diagram https://raw.githubusercontent.com/for-GET/http-decision-diag... (docs https://github.com/for-GET/http-decision-diagram/tree/master... ) and this: https://github.c…

> Only because we never had the tools and resources that, say, GraphQL has. GraphQL promised to solve real-world problems. What real world problems does HATEOAS addresses? None.

GraphQL was "promising" something because it was a thing by a single company.

HATEOAS didn't need to "promise" anything since it was just describing already existing protocols and capabilities that you can see in the links I posted.

And that's how you got POST-only GraphQL which for years has been busily reinventing half of HTTP

Re: Most RESTful APIs aren't really RESTful

#516

Post by Jenk »

jcelerier wrote: post #456
tbrownaw wrote: post #454

Earlier quoted context omitted.

Sometimes you need your timestamps to be in a named timezone. If I have a meeting at 9am local time next month, I probably want it to still be at 9am even if the government suddenly decided to cancel daylight time.

unless the customer you're meeting is in another timezone where the government didn't cancel daylight time

Exchange/GMail/etc. already has this problem/feature. Their response is simple: Follow the organiser's timezone. If it's 9am on the organiser's calendar, it will stay at 9am on the organiser's calendar. Everyone else's appointment will float to match the organiser.

Re: Most RESTful APIs aren't really RESTful

#517

Post by Jenk »

theamk wrote: post #412
yndoendo wrote: post #333

Earlier quoted context omitted.

Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.

I don't think I ever needed something like that... Since most cases don't need local time zone, why not keep two separate fields?

It's a delimited string. There are many fields within that string already.

    "2025-07-10T09:48:27+01:00"
That contains, by my quick glance, at least 8 fields of information. I would argue the one field it does not carry but probably should is the _name_ of the timezone it is for.

Re: Most RESTful APIs aren't really RESTful

#518

Post by ivan_gammel »

esafak wrote: post #451
ivan_gammel wrote: post #420

Earlier quoted context omitted.

That API doesn’t look like REST level 3 API. For example, there’s an endpoint to create a node. It is not referenced by root or anywhere else. GetNode endpoint does include some traversal links in response, but those links are part of domain model, not part of the protocol. HAL does offer a protocol by which you enhance your domain model with links with semantics and additional resources.

these levels? https://blog.restcase.com/4-maturity-levels-of-rest-api-desi...

Yes. Though more canonical link is here: https://martinfowler.com/articles/richardsonMaturityModel.ht...

Re: Most RESTful APIs aren't really RESTful

#519

Post by Jenk »

motorest wrote: post #489
SJC_Hacker wrote: post #425

Earlier quoted context omitted.

JSON doesn’t really have data types beyond very simple ones

> JSON doesn’t really have data types beyond very simple ones What do you think primitive types are supposed to be?

The below type definition (TS) fits the ECMA schema for JSON:

    type JSON = 
      string |
      number |
      boolean |
      null |
      JSON[] |
      {[name: string]: JSON}

Re: Most RESTful APIs aren't really RESTful

#520

Post by ivan_gammel »

motorest wrote: post #500
ivan_gammel wrote: post #223

Earlier quoted context omitted.

You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. This is the discoverability. It does not imply g…

> You have got it wrong. Let's say I build some API with different user roles. Some users can delete an object, others can only read it. The UI knows about the semantics of the operations and logical names of it, so when UI gets the object from server it can simply check, if certain operations are available, instead of encoding the permission checking on the client side. Have you ever heard of HTTP's OPTIONS verb? ht…

Maybe you should reconsider the way you ask questions on this forum. Your tone is not appropriate and the question itself just demonstrates that you don't understand this topic.

Yes, I'm aware of this header and know the web standards well enough.

In hypermedia API you communicate to client the list of all operations in the context of the resource (note: not ON the resource), which includes not only basic CRUD but also operations on adjacent resources (e.g. on user account you may have an operation of sending a message to this user). Yes, in theory one could use OPTIONS with a non-standard response body to communicate such operations that cannot be expressed in plain HTTP verbs in Allow header.

However such solution is not practical, because it requires an extra round trip for every resource. There's a better alternative, which is to provide the list of operations with the resource using one of the common standards - HAL, JSON-LD, Siren etc. The example in my another comment in this thread is based on HAL. If you wonder what is that, look no further than at Spring - it does support HAL APIs out of the box from quite a long time. And of course there's an RFC draft and a Wikipedia article (https://en.wikipedia.org/wiki/Hypertext_Application_Language).

Post reply on HN