readium
Documentation errors and lacking important information
Hello, I'm trying to implement a CMS plugin using the endpoints of LCP and LSD servers, but the documentation is totally partial and contains many errors. First of all, all the links to response errors land in 404 pages, example: http://readium.org/license-status-document/error/unauthorized I cannot find any description of licenses states (when a license becomes active, when becomes ready, which are the possible states). The documentation for revoking licenses is wrong: https://github.com/readium/readium-lcp-server/wiki/LCP-Status-Server-API#revokecancel-a-license The status to pass is not 'cancel' or 'revoke', but 'cancelled' or 'revoked'. The 'message' parameter in the example does nothing (I'm wrong?).
To discover real endpoints of LCP and LSD servers, I have to look at code, because they're undocumented.
Thank you
Hello,
There are several items there.
- all the links to response errors land in 404 pages, example: http://readium.org/license-status-document/error/unauthorized
This is not a mistake. In this case, URLs are used as error codes, they do not need to be dereferencable. The client application will compare the received value with a set of constant values, it will not follow the link. One can argue that having a URL point to a real Web resource is good practice: this is true. We'll think about adding Web pages at these places.
- I cannot find any description of licenses states (when a license becomes active, when becomes ready, which are the possible states
Did you read the Readium LCP specification? If yes, maybe you didn't spot the list of license states.
- The documentation for revoking licenses is wrong: The status to pass is not 'cancel' or 'revoke', but 'cancelled' or 'revoked'.
Good catch. Corrected in the wiki.
- The 'message' parameter in the example does nothing.
That's right. It has never been used in practice. Now removed from the example.
- To discover real endpoints of LCP and LSD servers, I have to look at code, because they're undocumented.
Can you please tell us which useful endpoints are missing from the wiki?
About the point 1:
This is not a mistake. In this case, URLs are used as error codes, they do not need to be dereferencable.
This is totally counterintuitive, a string formatted as an URL should reference a real resource. About the point 2, thanks for the clarification. Points 3 and 4: now the documentation is better, but there's still an error. By looking to the source code, no error 400 is thrown if the requested status is 'revoked' and the license is 'ready', but the requested status is silently translated to 'cancelled'. This is useful because the CMS can call 'revoked' without checking if actual state is 'ready' or 'active'. About the point 5: all LCP and LSD endpoints should be documented to let users do what they want. For example, I needed to DELETE publications and GET partial licenses. Maybe I'll need other as the development grows.
Thanks for your support
Discussions relative to dereferenceable URIs in the Semantic Web are old discussions (for instance here).
no error 400 is thrown if the requested status is 'revoked' and the license is 'ready', but the requested status is silently translated to 'cancelled'.
True. I just clarified the wording in the Wiki.
all LCP and LSD endpoints should be documented ... Delete a publication ...
True. But I won't have the time to do it in the short term (open-source developers always believe that the code is the documentation).