1 Reply Latest reply on May 19, 2009 2:54 PM by matt.walker

    A few document-related REST API questions

      We'd like to use Jive to publish the official documentation for our software product, and I have a few questions that have come up from trying to use the REST API to make this happen.

       

      1) The createDocument method's documentation says that I need a "documentTypeID" -- where do I go to find a listing of the document types and their IDs?  The REST API docs section on the documentService doesn't contain it, and I'm having trouble locating it among the other developer docs.

       

      2) This piece from the createDocument method's documentation on the documentID attribute is confusing to me:

       

      the document ID of the new document. If null a default is created. If not null must start with 'tempDoc-' or the prefix value in 'jive.temporaryDocPrefix'.

       

      Why do I need to manually create a doc ID?  The system seems to create one for me if I use the web UI.  Also, can this ID be a descriptive string (i.e. something intended to be part of a URL), or is it supposed to be a number?

       

      3)  What's the best way to namespace our documents by release so that we can have URLs like "/community/documentation/2.4/<DOCS DOCUMENT>"?  Just creating a new subspace under documentation for every version of the docs -- e.g. "2.4", "2.5", etc?

       

      4) Do I have any control over the URL for an individual document? Instead of "/community/documentation/2.4/DOC-2002" I'd like to have something like "/community/documentation/2.4/snmp-api-guide" -- i.e. reflecting the docs internal divisions in the URLs as well as the content.

       

      thanks for any help!

       

      -TR

        • Re: A few document-related REST API questions

          1) The createDocument method's documentation says that I need a "documentTypeID" -- where do I go to find a listing of the document types and their IDs?  The REST API docs section on the documentService doesn't contain it, and I'm having trouble locating it among the other developer docs.

          A documentTypeID of 1 is applicable for almost all common operations.  I'd stick with this unless you have a very exotic use case.  Agreed, this should be better documented.

          2) This piece from the createDocument method's documentation on the documentID attribute is confusing to me:

           

          the document ID of the new document. If null a default is created. If not null must start with 'tempDoc-' or the prefix value in 'jive.temporaryDocPrefix'.

           

          Why do I need to manually create a doc ID?  The system seems to create one for me if I use the web UI.  Also, can this ID be a descriptive string (i.e. something intended to be part of a URL), or is it supposed to be a number?

          Stick with null in this case.  If you had some other need to keep track of a doc ID (which must be a number) you could use an alternative, but for basic use null is sufficient.

          3)  What's the best way to namespace our documents by release so that we can have URLs like "/community/documentation/2.4/<DOCS DOCUMENT>"?  Just creating a new subspace under documentation for every version of the docs -- e.g. "2.4", "2.5", etc?

          Have you seen our out of the box document version management?  Let me know how it fails to satisfy your use case and I can provide further advice.

          4) Do I have any control over the URL for an individual document? Instead of "/community/documentation/2.4/DOC-2002" I'd like to have something like "/community/documentation/2.4/snmp-api-guide" -- i.e. reflecting the docs internal divisions in the URLs as well as the content.

          We have configurable URLs for Spaces, Groups, and Blog Posts, but not for individual documents.  You could accomplish this with an Apache mod_rewrite rule, though.