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

Implementing Microsoft REST API Filter

sergeykibish.com

Post reply on HN
Print view View original

11–20 of 44 posts

Re: Implementing Microsoft REST API Filter

#11

Post by jgalt212 »

voidfunc wrote: post #3
recursivedoubts wrote: post #2

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

You can tap the sign as much as you want, that battle was lost a long time ago. REST is just the common term people use for HTTP+JSON RPC.

True that. I use it incorrectly with non-technical folk as they may understand what a REST API is, but when I say "it's more like an RPC interface" their eyes glaze over.

Re: Implementing Microsoft REST API Filter

#12

Post by deathanatos »

nightpool wrote: post #8
deathanatos wrote: post #6

Earlier quoted context omitted.

… and it's not just the hyperlinking that's problematic. (Yeah, MS's unRESTful "RESTful" APIs do a huge amount of coupling in the form of URL building.) E.g., in Azure, which is also a "RESTful" API that has no idea what REST is about, MS completely misses Fielding points that most of the effort of definition should be spent defining the content / data's format, not things like URL structure. That way we can speak ab…

I'm not sure how you're blaming JSONSchema for "Half the fields in the type will be required … and the schema will say they're optional". But JSONSchema has plenty of ways to define sum types: http://json-schema.org/understanding-json-schema/reference/c...

Hmm. Thank you for that, I seem to be mistaken there. I wonder if that was added after I acquired my knowledge of JSONSchema? Or if it was some weird thing w/ Swagger where it wasn't supported there.

Re: Implementing Microsoft REST API Filter

#13

Post by XVincentX »

deathanatos wrote: post #12
nightpool wrote: post #8

Earlier quoted context omitted.

I'm not sure how you're blaming JSONSchema for "Half the fields in the type will be required … and the schema will say they're optional". But JSONSchema has plenty of ways to define sum types: http://json-schema.org/understanding-json-schema/reference/c...

Hmm. Thank you for that, I seem to be mistaken there. I wonder if that was added after I acquired my knowledge of JSONSchema? Or if it was some weird thing w/ Swagger where it wasn't supported there.

Swagger (OpenAPI 2) and OpenAPI 3 never supported JSON Schema. They support a subset of the draft 4 with custom additions. OpenAPI 3.1 added support for additional schemas where you can use whichever draft you want.

Re: Implementing Microsoft REST API Filter

#14

Post by masklinn »

rafale wrote: post #7
voidfunc wrote: post #3

Earlier quoted context omitted.

You can tap the sign as much as you want, that battle was lost a long time ago. REST is just the common term people use for HTTP+JSON RPC.

You gotta say RESTful if you want to emphasis RESTfulness. But I personally don't care. I don't mind JSON RPC.

Then say that?

Rest pedants don’t care if you don’t use rest, as long as you don’t call it rest. It’s hardly a difficult concept.

Re: Implementing Microsoft REST API Filter

#15

Post by deathanatos »

XVincentX wrote: post #9
deathanatos wrote: post #6

Earlier quoted context omitted.

… and it's not just the hyperlinking that's problematic. (Yeah, MS's unRESTful "RESTful" APIs do a huge amount of coupling in the form of URL building.) E.g., in Azure, which is also a "RESTful" API that has no idea what REST is about, MS completely misses Fielding points that most of the effort of definition should be spent defining the content / data's format, not things like URL structure. That way we can speak ab…

Disclaimer: I work for Microsoft as an API Architect. I am not working on this specific API, so I am not going to comment on anyway. I hear your complains about Microsoft API guidelines (which is an entire different conversation) but I wanted to add my two cents with regards to JSON Schema. The problem that I have been having with JSON Schema since forever - is that the data that is being modeled is complected with c…

I'm not sure what you mean by "it is very hard to give contextuality on it"; OAS does supports referring to a type by reference, so that higher level types can reuse the definition of structs they might contain.

But even so, here the problem is that the APIs aren't actual PUT/GETs: they payload types aren't the same going up as they are coming down. It is really two separate types, one for PUT, one for GET.

Some of that is to be expected (there will be some information after the create that is only added by the VM coming into being) but how Kubernetes handles this with a separate "status" for the item I think ends up letting the rest of the type (spec, in k8s's case) be the same type. (… ish. K8s has variants of this problem, too.)

To expand a bit, I'm largely relegated to the API docs themselves. Browsing the actual schema is hard:

  Start at: https://github.com/Azure/azure-rest-api-specs
  Descend into specification.
  Descend into … so many choices … compute.
  Descend into resource-manager.
  Descend into Microsoft.Compute
  Descend into stable
  Descend into — and this is tricky!
    the latest version isn't the latest version.
    The latest version is 2022-04-04, but for VM creation it's 2022-03-01.
    The only way I know to determine this is to seek backwards, or find it in the docs.
  Descend into ComputeRP
  Descend into virtualMachine.json.
And it's 3.3k LoC! Some of this verbosity is JSONSchema, to be sure… but still. And then you might have to wade back up to common.json, though I forget what circumstances cause me to need to look there.

Re: Implementing Microsoft REST API Filter

#16

Post by masklinn »

deathanatos wrote: post #12
nightpool wrote: post #8

Earlier quoted context omitted.

I'm not sure how you're blaming JSONSchema for "Half the fields in the type will be required … and the schema will say they're optional". But JSONSchema has plenty of ways to define sum types: http://json-schema.org/understanding-json-schema/reference/c...

Hmm. Thank you for that, I seem to be mistaken there. I wonder if that was added after I acquired my knowledge of JSONSchema? Or if it was some weird thing w/ Swagger where it wasn't supported there.

Might just be confusion with swagger / openapi, which is a complete mess of procedural constraints reminiscent of XML Schemas.

Re: Implementing Microsoft REST API Filter

#17

Post by voidfunc »

masklinn wrote: post #14
rafale wrote: post #7

Earlier quoted context omitted.

You gotta say RESTful if you want to emphasis RESTfulness. But I personally don't care. I don't mind JSON RPC.

Then say that? Rest pedants don’t care if you don’t use rest, as long as you don’t call it rest. It’s hardly a difficult concept.

Yea, but nobody cares what REST pedants think.

Re: Implementing Microsoft REST API Filter

#18

Post by derefr »

recursivedoubts wrote: post #2

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

A true REpresentational State Transfer API would give each version of each of the API's L7-protocol request and response messages its own media-(sub)type; and would then rely on HTTP content negotiation to allow clients to specify which messages they're expecting to receive in response to a request; where the difference between throwing/nonthrowing, sync/async, new/old variant, etc., would all come down to which response message types the client is declaring themselves to accept.

Don't think I've literally ever seen this done in practice. Don't think I've ever seen a "REST client" library that even offers the possibility of negotiating with a backend that's attempting to do this — let alone doing it in a streamlined manner.

Re: Implementing Microsoft REST API Filter

#19

Post by vxNsr »

recursivedoubts wrote: post #2

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

Hey, I’m kinda new to this area, can you show with examples what the differences are? I read the article, he does a lot of explaining but doesn’t do much showing. Like why is a specific api more RPC and why a different one is a perfectly constructed REST api?

Re: Implementing Microsoft REST API Filter

#20

Post by recursivedoubts »

derefr wrote: post #18
recursivedoubts wrote: post #2

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

A true REpresentational State Transfer API would give each version of each of the API's L7-protocol request and response messages its own media-(sub)type; and would then rely on HTTP content negotiation to allow clients to specify which messages they're expecting to receive in response to a request; where the difference between throwing/nonthrowing, sync/async, new/old variant, etc., would all come down to which resp…

no, the whole media type thing was a moderately-interesting-idea-turned-ridiculous-navel-gazing turn that, among many other pedantic blind alleys, turned everyone away from the deeply innovative aspect of REST: the uniform interface, and, in particular, HATEOAS

https://htmx.org/essays/hateoas/

any idiot (such as myself) who has ever made a web 1.0 app has created a better REST API than 99.9% of all REST API engineers, so called

Post reply on HN