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

An OpenAPI proxy that only allows data that matches your swagger.json

github.com

Post reply on HN
Print view View original

11–15 of 15 posts

Re: An OpenAPI proxy that only allows data that matches your swagger.json

#11

Post by smt88 »

_asummers wrote: post #2

I've found OpenAPI is very poor for more dynamic resource-based APIs where the mechanics of interactions between the resources is standard but the resources themselves differ, e.g. a JSONAPI API. Does anyone know of tooling that more accurately fits that use case? I have hand rolled (well, generated) JSON Schemas in the past and published those, but that felt unsatisfying and too ad hoc.

OpenAPI v3 can handle what you describe, although it's a pain to write it by hand and tooling in your language may be missing support for edge cases (i.e. incomplete spec implementation).

My suggestion would be to define your APIs in a neutral, flexible format (such as Spot[1]) and then generate OAS 3 or whatever other formats you need. That helps you avoid lock-in and any tedium required to handle less-capable formats.

1. https://github.com/airtasker/spot

Re: An OpenAPI proxy that only allows data that matches your swagger.json

#12

Post by Nullabillity »

ekseda wrote: post #7
peterkelly wrote: post #6

https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-va...

Check out the readme. There are many erros that can only be catched by validation and not by parsing.

There is a difference between the common meaning of parsing (text -> (ast | error)) and the generalized meaning that Alexis uses in the post (less structured -> (more structured | error)).

Re: An OpenAPI proxy that only allows data that matches your swagger.json

#13

Post by Nullabillity »

smt88 wrote: post #8
peterkelly wrote: post #6

https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-va...

How do you see this as relevant to a REST API? Many people would need additional tooling to parse JSON into a structured type, especially in dynamic languages where unstructured data types are the norm. And even if you do that, you're still going to have to validate the data and tell the client where they might have messed up the formatting. Parsing is a totally fine, low-cost, low-risk way to validate chunks of JSON…

> Many people would need additional tooling to parse JSON into a structured type, especially in dynamic languages where unstructured data types are the norm.

Well, there's your first issue. Specifying your formats is a good idea, regardless of language. And this is completely possible in dynamic languages too, see for example Python's Marshmallow.[0]

> And even if you do that, you're still going to have to validate the data and tell the client where they might have messed up the formatting.

The point is that you should take the opportunity to encode this validation in your types. A validated email address is no longer a `String`, it's an `Email`, with different valid operations. Or for an extreme example, you (hopefully) wouldn't try do time calculations directly on RFC 3339 strings.

This doesn't have to happen at exactly the same time as parsing the JSON AST, it's completely sensible to go JSON -> JSON AST -> Model.

[0]: https://marshmallow.readthedocs.io/en/stable/

Re: An OpenAPI proxy that only allows data that matches your swagger.json

#14

Post by p_l »

prescojan wrote: post #5

Isn't REST just a glorified SOAP at this point? Predefined schema, generate classes from schema, interact with it via HTTP.

REST is often used as a very, very limited transport model for a two-bit, buggy, incomplete and incoherent clone of SOAP, yes.

Unfortunately, neither REST nor SOAP are understood by majority of developers writing code for them (to this day, I insist that the real issue with SOAP was people using IDE code generation without ever studying how SOAP works)

Re: An OpenAPI proxy that only allows data that matches your swagger.json

#15

Post by smt88 »

Nullabillity wrote: post #13
smt88 wrote: post #8

Earlier quoted context omitted.

How do you see this as relevant to a REST API? Many people would need additional tooling to parse JSON into a structured type, especially in dynamic languages where unstructured data types are the norm. And even if you do that, you're still going to have to validate the data and tell the client where they might have messed up the formatting. Parsing is a totally fine, low-cost, low-risk way to validate chunks of JSON…

> Many people would need additional tooling to parse JSON into a structured type, especially in dynamic languages where unstructured data types are the norm. Well, there's your first issue. Specifying your formats is a good idea, regardless of language. And this is completely possible in dynamic languages too, see for example Python's Marshmallow.[0] > And even if you do that, you're still going to have to validate t…

OK, I understand what you're saying. OpenAPI can be used for what you're describing. I just don't really understand the false dichotomy between validation and parsing. OpenAPI can be used for both depending on the language, and if you're writing docs, you might as well write them in OpenAPI format and get a validator for free.
Post reply on HN