Hard to maintain Plone REST API sync with plone.server

[bloodbare]

I'm trying to keep track of development on plone.restapi in order to apply the same REST implementation on plone.server but it gets hard dues to not a specification. I would say that we need to have some kind of list:

Content Type + HTTP VERB + named endpoint : functionallity + example input/output

Where its forced that pull requests have this document updated before commiting or edditing the API.

@tisto

[lukasgraf]

@bloodbare I feel your pain. I'm in a similar situation with providing a customer of ours with a changelog of (breaking) API changes between updates.

I can see a couple points where we can address this:

• The CRUD example requests/responses in the docs are currently hardcoded. These should also be dynamically produced request/response dumps like the other ones in test_documentation.py, so that they're always up to date.

• We need to make sure that if changes in a pull-request cause changes in such a request/response dump, the dump is always updated (preferably in the same commit that introduces the change). Also see Update types_document.json to be up-to-date with current implementation. #138.

• We should have a test for that. If a PR is opened that results in git diff docs/source/_json/ producing non-empty output, some test somewhere should fail.

  Need to think about how exactly to integrate this with local runs of the test suite vs. Travis CI vs. GitHub Status checks though. Also, discrepancies in the output between Plone 4 vs. Plone 5 - if we say plone-4.3.x.cfg is the canonical version of the output, only those tests should fail.

• Changelog. Since the 1.0a1 release we've got a CHANGES.rst that needs to be kept up to date. That might not tell you the details about what exactly has changed, but at least it should always cover the fact that something has been changed, and you need to look into it.

[tisto]

Closing issue in favor of: #162