4 ms·

> > - JSON has no comments. Or version designators. > Indeed, and it's all the better for it. JSON5 attempts to fix the comments problem: https://json5.org/ h

> > - JSON has no comments. Or version designators. > Indeed, and it's all the better for it. JSON5 attempts to fix the comments problem: https://json5.org/ https://json5.org/ A lack of comments is never good, especially when you want to provide a workable example of what an entity looks like, while annotating its contents, but at the same time allowing it to be parseable. Furthermore, i wouldn't scoff if i ever saw comments about non-trivial fields in web APIs actually being returned, to better explain how to use them. Of course, at the same time i believe that something like that would be better suited as a part of WSDL, WADL or XSD schemas, but JSON and the technologies around it have essentially done away with strict schemas, which makes using them about as reassuring as dynamic languages - i.e. unreliable. Far too few people do properly versioned APIs and far too few people do OpenAPI specs that are generated from code automatically and are publicly available for the above to be a moot point. Whereas with XML based services, i could open the WSDL/XSD file for a 15 year old API and know what's going on within 10 minutes. It seems like the industry has lost that bit of wisdom somewhere along the way of chasing agility - the same way that knowing how to generate code and operate with metamodels and models has also been tossed aside.

thaumasiotes 5y ago
> JSON5 attempts to fix the comments problem: https://json5.org/ https://json5.org/ It also attempts to fix some other problems. I'm fond of "numbers may be hexadecimal". I can't resist observing how much easier the fixes would be, if JSON data included a version designator.
GoblinSlayer 5y ago
JSON schemas are useless anyway, because web apis are dynamic and change daily.
- KronisLV 5y ago
  Maybe that's the problem, then? You can't expect a number from an API and get a boolean back, without your system breaking. There should be contracts between any two parts of a system, or any interlinked systems. It's inexcusable to have breaking changes without doing something to give the users the ability to react to them before breakage: be it changing the signatures and deprecating the old methods for libraries which would be picked up by CI and would not build the code before these being addressed, or changing a WSDL/WADL/OpenAPI service description, which would then propagate into failing integration tests before new versions would be deployed. You'd get a JSON schema of v14 and then another of v15 which would introduce breaking changes, but all of the downstream systems would see the changes and essentially figure out that they cannot use this new API (ideally, in a scheduled and automated process). So essentially, it would be like this: - you have an old API version that is used - for example: your-app.com/api/v14/pictures/cats/bambino?size_x=640&size_y=480&page=5 - the new API version would get released, which would change paging semantics - your-app.com/api/v15/pictures/cats/bambino?size_x=640&size_y=480&count=10&offset=40 - the CI system would pick up changes from /api/v14.json and /api/v15.json service descriptions - it would detect breaking changes and developers would be alerted (either automatically as a part of integration tests, or when trying to update integrations) - they'd update the API integration to address these issues, before the old would eventually be sunsetted Alternatively, even a header about deprecation being returned on the current API endpoint would be better than one day just discovering that production has broken: https://tools.ietf.org/id/draft-dalal-deprecation-header-03.html https://tools.ietf.org/id/draft-dalal-deprecation-header-03.... Of course, sadly most companies out there aren't interested in versioning their APIs or even providing any sorts of service descriptions, because all of that costs money and time. So in the moniker of "Move fast and break things" the focus ends up being on the second part.

thaumasiotes 5y ago

> JSON5 attempts to fix the comments problem: https://json5.org/ https://json5.org/ It also attempts to fix some other problems. I'm fond of "numbers may be hexadecimal". I can't resist observing how much easier the fixes would be, if JSON data included a version designator.

GoblinSlayer 5y ago

JSON schemas are useless anyway, because web apis are dynamic and change daily.

KronisLV 5y ago
Maybe that's the problem, then? You can't expect a number from an API and get a boolean back, without your system breaking. There should be contracts between any two parts of a system, or any interlinked systems. It's inexcusable to have breaking changes without doing something to give the users the ability to react to them before breakage: be it changing the signatures and deprecating the old methods for libraries which would be picked up by CI and would not build the code before these being addressed, or changing a WSDL/WADL/OpenAPI service description, which would then propagate into failing integration tests before new versions would be deployed. You'd get a JSON schema of v14 and then another of v15 which would introduce breaking changes, but all of the downstream systems would see the changes and essentially figure out that they cannot use this new API (ideally, in a scheduled and automated process). So essentially, it would be like this: - you have an old API version that is used - for example: your-app.com/api/v14/pictures/cats/bambino?size_x=640&size_y=480&page=5 - the new API version would get released, which would change paging semantics - your-app.com/api/v15/pictures/cats/bambino?size_x=640&size_y=480&count=10&offset=40 - the CI system would pick up changes from /api/v14.json and /api/v15.json service descriptions - it would detect breaking changes and developers would be alerted (either automatically as a part of integration tests, or when trying to update integrations) - they'd update the API integration to address these issues, before the old would eventually be sunsetted Alternatively, even a header about deprecation being returned on the current API endpoint would be better than one day just discovering that production has broken: https://tools.ietf.org/id/draft-dalal-deprecation-header-03.html https://tools.ietf.org/id/draft-dalal-deprecation-header-03.... Of course, sadly most companies out there aren't interested in versioning their APIs or even providing any sorts of service descriptions, because all of that costs money and time. So in the moniker of "Move fast and break things" the focus ends up being on the second part.