I think he means that the UK govt has mandated a particular CSV standard for tabular data, at the same time. I think you're right that OpenAPI has nothing to do with CSV.
Yes. CSV with the obvious extra conditions "UTF-8" and "one header row" is fairly interoperable, but note: "when you’re using Excel for Windows to load a file that is UTF-8 without a BOM, you can resolve the display of non-ASCII characters by using the ‘import text’ option". If a Windows user just clicks on the file then sometimes UTF-8 is interpreted as some 8-bit encoding and you get mojibake. Nevertheless, you shouldn't add a BOM because the standard doesn't permit that and it might cause all sorts of problems on other systems.
Is that true? Iirc Openapi lets you define schemata for csv payloads in POST body sections. Whether they are validated by the backends is another question...
I spent a while looking through the registered birth names data for about 5 years while we were naming our kids. Each year was in Excel sheets, which changed format repeatedly. It was really annoying.
Moving over to providing everything as well formatted CSVs is going to be so much nicer.
We use Connexion at work, which supports v3 now (though we haven't gotten around to updating it from 2 yet). If you use python/flask, I _highly_ recommend checking out Connexion: https://github.com/zalando/connexion
Anyone know/recommend any API schemas/standards for REST APIs that allow machines to discover their resources?
For example I see OpenApi v3 mentioned here (which uses a yaml file to give context) and I am also familiar with NGSIv2[1] which will get standardized by ETSI supposedly (NGSI-LD[2]). NGSI seems to embed info in the json so that your application can know if this float is Celsius or Fahrenheit.
That is a fascinating question. Mostly because I wasn't around for SOAP. I started my development career kind of with the rise of REST. I've only ever used REST personally, so I couldn't really tell you. Looking up WSDL, I can tell you one thing I've noticed with OpenAPI is that it is both incredibly descriptive, and yet not in the way. I can look at an OpenAPI file, figure out what is going really quickly and get working. With WSDL/XML you have to parse the whole XML schema to really understand what is going on.
As someone working on GOV.UK projects and regularly working with large, unwieldy CSVs I can't recommend CSVKit[0] highly enough. Being able to go from CSV to PostgreSQL in one or two simple steps is _priceless_ for me.
Unfortunately, actual usability seems to be getting ignored in the rush for a "standard". In the meantime, you might want to consider using RAML. It compiles to OpenAPI and is far more optimized for use by humans instead of machines.
33 comments
[ 3.3 ms ] story [ 70.6 ms ] threadLinks:
https://openapi.tools/
https://tools.ietf.org/html/rfc4180
While using the open API spec is good, I'd say the standardisation of CSV data will have more impact. More of the open data available is in the form of historic reports rather than real-time: https://data.gov.uk/ (e.g. https://data.gov.uk/dataset/27dd8d7f-c58b-4de3-bf0d-81058465...)
https://en.wikipedia.org/wiki/Mojibake
love this word!
Moving over to providing everything as well formatted CSVs is going to be so much nicer.
I think it's in JsonSchema validation and Open Api v3 but not v2.
For example I see OpenApi v3 mentioned here (which uses a yaml file to give context) and I am also familiar with NGSIv2[1] which will get standardized by ETSI supposedly (NGSI-LD[2]). NGSI seems to embed info in the json so that your application can know if this float is Celsius or Fahrenheit.
Any other open options?
[1]: https://fiware.github.io/specifications/ngsiv2/stable/ [2]: https://fiware-datamodels.readthedocs.io/en/latest/ngsi-ld_f...
https://json-ld.org/
https://www.hydra-cg.com/
That said, hmm, what do you feel like OpenAPI learned (so as not to repeat) from the pitfalls of SOAP WSDLs?
As someone working on GOV.UK projects and regularly working with large, unwieldy CSVs I can't recommend CSVKit[0] highly enough. Being able to go from CSV to PostgreSQL in one or two simple steps is _priceless_ for me.
[0] https://csvkit.readthedocs.io/en/latest/
https://www.postgresql.org/docs/12/sql-copy.html
I've seen a couple of meta generator projects that generate OpenAPI specs from a meta description.
Is anything being done 'officially' to provide an abbreviated form for simpler use cases?
Source https://swagger.io/docs/specification/about