Clarity

Expand all | Collapse all

REST API Documentation

Deactivated User

Deactivated UserMay 16, 2016 03:12 PM

  • 1.  REST API Documentation

    Posted Apr 28, 2016 03:21 PM

    Does anyone have any detailed information on how to utilize the REST APIs in CA PPM?  CA has promoted the updates to their REST APIs in 14.4, but have not really provided any insight on how to utilize them.  I've tried accessing the URLs in the 14.3 documentation on a 14.3 environment (OnDemand), but the URLs give me an Error 404 message.

     

    Can anyone point me to some useful documentation or discuss how they have utilized the REST APIs?



  • 2.  Re: REST API Documentation
    Best Answer

    Posted May 16, 2016 04:47 AM

    Log in as an Admin with rest access.

    Look under system options, see the API section.

    api_rest.png

    grab the API documentation URL and paste it in..

    rest_api_help.PNG

     

    Have you set the http entry URL in the CSA yet?



  • 3.  Re: REST API Documentation

    Posted May 16, 2016 03:12 PM

    So not covered in the standard CA PPM documentation?



  • 4.  Re: REST API Documentation

    Posted May 17, 2016 03:22 AM

    No, it's not.

    you can find the basic information in the link below, but the actual reference material is in the API documentation url on your host.

    https://docops.ca.com/ca-ppm/14-4/reference/rest-apis



  • 5.  Re: REST API Documentation

    Posted May 17, 2016 03:38 PM

    That was a rhetoric question.

    John_George and CA-TECH-INFO-DAMON have been doing  a great job on improving the content and usability and single access to various resouces (thank you) and I was just in a round about way trying to catch their attention for one more source to be added.



  • 6.  Re: REST API Documentation

    Posted May 17, 2016 04:36 PM

     

    I love the above. Especially since I have 3 kids



  • 7.  Re: REST API Documentation

    Posted May 18, 2016 08:16 AM

    Hi everyone, interesting discussion. I'm tagging our documentation SME who has written the REST API documentation. Sarmistha_Purkayastha - can you help us out here?

     

    Thanks,

     

    John



  • 8.  Re: REST API Documentation

    Posted May 18, 2016 11:51 AM

    Hello all,

     

    Andrew Mowlam has correctly pointed out above how to access the REST API documentation. Here's a link to this information in the 14.4 documentation:

    REST APIs - CA PPM - 14.4 - CA Technologies Documentation

     

    For your convenience, I am also pasting below the relevant information from this section. After logging in to CA PPM, open a separate tab and paste the URL for the REST API reference documentation (provided in the below section that I have pasted here) to access the documentation.

    ---------------

    Access the APIs and Reference Documentation

    Use the following URL structure to access the REST APIs:

    https://<hostname>:<port>/<context>/rest/<api-version>/<resource-name>

    Example: https://samplehost:8080/ppm/rest/v1/projects

    Where

    • ppm is the default web context for the REST APIs
    • "v1" is the only supported API version for the current release
    • projects is the CA PPM object that the REST API is accessing

    Use the following URL to access the REST API reference documentation and all supported end points:

       https://<hostname>:<port>/niku/rest/describe/index.html

    You can also invoke the endpoints from this URL. See Sample API Requests and Responses for more information. Verify that you are logged in to CA PPM to access the REST API documentation URL.

    Note: The web context for the REST API URL is configurable only for the On-Premise customers. See CSA Server Properties to learn how to configure the web context for the REST API URL. In addition, you can learn how to enable or disable the REST API access.

    ------------------

    The topic for which I have provided the URL above includes information about how to verify that you have access to the REST APIs. There is other high-level, introductory information about the REST APIs. For detailed information about the API end points, how to use the REST APIs,  and access the API end points, please use the URL provided in the above section "Access the APIs and Reference Documentation".

     

    Do let me know if you have any other feedback, concerns, or questions about the REST API documentation and I will try to address them here to the best of my ability.

     

    Best Regards,

    Sarmistha



  • 9.  Re: REST API Documentation

    Posted May 18, 2016 12:12 PM

    Hi Sarmistha,

    thanks for what you've done so far, I like it.

    it might be worth doing a "getting started with REST" Tuesday tip.  i.e. what tools to use, how to authenticate and go through a hello world example



  • 10.  Re: REST API Documentation

    Posted May 18, 2016 12:23 PM

    Hi Andrew,

    That sounds like a good idea to me. I will add to my backlog for now and will try to work with development to come up with a getting started topic for the REST APIs.

     

    Thanks for suggesting it.



  • 11.  Re: REST API Documentation

    Posted May 19, 2016 10:51 AM

    For other who follow this tread,I just posted a video to help getting started  Getting started with Rest API

    with two excel spreadsheet you can download and play with.

     

    It is not a replacement for the  professional material  coming from CA but it might be enough for some people to get started

     

    Andrew... thank you for your comment on the other thread I see you already took a look at it.



  • 12.  Re: REST API Documentation

    Posted May 19, 2016 11:00 AM

    I was going to do something similar, but you beat me to it



  • 13.  Re: REST API Documentation

    Posted May 20, 2016 08:41 AM

    :-)



  • 14.  Re: REST API Documentation

    Posted May 18, 2016 12:12 PM

    Thank you for posting that-

    mike2.2 did not seem to be that pleased with my rhetoric question  so I ask for real:

    Is there a reason why that is not where the other 14.4 documentation is and when might that be included there?



  • 15.  Re: REST API Documentation

    Posted May 18, 2016 12:30 PM

    Hello Urmas,

     

    The REST API reference documentation is not included in the standard product documentation in DocOps because the reference documentation is generated automatically from the code by our API developers. They use a tool called Swagger to generate, maintain, and update the reference documentation. This is a much more efficient way to manage the API end point documentation. From our standard documentation on DocOps, we provide links to the API reference documentation.



  • 16.  Re: REST API Documentation

    Posted May 18, 2016 03:01 PM

    Thank you  Sarmistha_Purkayastha for your answers.

    So it is determined by what is efficient for the developers and the content apparently freezed when the software is installed or upgraded and not based on user accessibility single source with continuous updates.

    Does it work on ondemand and on premise when the user does not have access to the file system on the server?



  • 17.  Re: REST API Documentation

    Posted May 18, 2016 03:21 PM

    Hi Urmas,

    You are very welcome!

    As per my understanding, this method of generating the API documentation ensures that the documentation always stays synchronized with the latest APIs. Both our On Premise and SaaS customers have access to the REST APIs and the reference documentation OOTB as long as they are authenticated and authorized. However, they have the option to disable the API access. Could you please specify exactly what you mean when you say "access to the file system on the server"?

     

    --Sarmistha



  • 18.  Re: REST API Documentation

    Posted May 18, 2016 03:37 PM

    I guess the major updates will be with version upgrades so only minor clarifications and such like will not get updated.

    It is very common where I have worked that CA PPM admins do not have access to the server file system eg cannot read the properties.xml file and other content in Clarity home.

    The access is only granted by internal IT for install and upgrade, but not continuously.



  • 19.  Re: REST API Documentation

    Posted May 18, 2016 03:41 PM

    mike2.2  is saying somewhat similar in

    Best way for deploying new feature



  • 20.  Re: REST API Documentation

    Posted May 18, 2016 08:16 PM

    Hi Urmas,

     

    Yes I agree that major updates to the reference docs will be with the version upgrades and not continuously as in DocOps. About your other query, I will need to check with the SMEs to see if they have any input.

     

    Thanks for your feedback, Sarmistha



  • 21.  Re: REST API Documentation

    Posted May 19, 2016 10:15 PM

    Hello Urmas,

    I verified with the SMEs that the Swagger web application is available to any registered user on a CA PPM instance that has the API access right assigned. On Premise versus SaaS does not matter. Also, there is no dependency on the file system.

     

    Hope this helps.

    Regards, Sarmistha



  • 22.  Re: REST API Documentation

    Posted May 20, 2016 04:23 AM

    Thank you  Sarmistha_Purkayastha 

    That is very good:

    The documentation is there and it can be accessed fairly easily.