3 ms·

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.

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.