document how to use REST API

[kdaily]

From https://sagebionetworks.jira.com/browse/PLFM-4795.

Some use cases coming up (that need more documentation from me) where using the REST API would be useful instead of one of the clients.

See the Jira issue for some example REST API docs structures.

[meredithslota]

Candidate for Synapse in Practice article, primarily targeted at developers and internal power users.

Topics:

1. Existence of the API
2. Common tools for working with the API (standard API requests) (key concern: want to be able to use API without the clients)
3. Links to our API REST docs
4. A small number of example calls

[meredithslota]

We commit to a v1 of this doc by June but reserve the right to punt more complex stuff until later.

[kdaily]

Of note, @jaeddy possibly got our API to work with Swagger...

[jaeddy]

Thanks @kdaily - I'll add some notes here on the process and results.

[jaeddy]

Building Swagger API docs for Synapse

Requirements

1. Clone the Synapse-Repository-Services repo
2. Create a new environment (e.g., with conda) and install [need to check for missing dependencies...]:
   • java-jdk (Must be jdk 8)
   • maven

     conda create -n synrest
     conda install -c bioconda java-jdk
     conda install -c conda-forge maven

Adding Enunciate and Springfox

Under /services/repository/...

1. Add the following to the pom.xml file in the dependencies section:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <scope>compile</scope>
</dependency>

2. Add the following to pom.xml in the build/plugins section:

<plugin>
    <groupId>com.webcohesion.enunciate</groupId>
    <artifactId>enunciate-maven-plugin</artifactId>
    <version>2.11.0</version>
    <executions>
        <execution>
            <goals>
                <goal>docs</goal>
            </goals>
            <configuration>
                <configFile>enunciate.xml</configFile>
                <docsDir>${project.build.directory}</docsDir>
            </configuration>
        </execution>
    </executions>
</plugin>

3. Add the following in a new file enunciate.xml in the services/repository/ directory:

<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.11.0.xsd">

    <application root="/rest" />
<!--    use to build Swagger docs for specific APIs, e.g. 'Activities'-->
<!--    <api-classes>-->
<!--        <include pattern="org.sagebionetworks.repo.web.controller.ActivityController"/>-->
<!--    </api-classes>-->
</enunciate>

4. Finally, (from within the /services/repository/ directory, run:

mvn compile

Viewing results

Navigate to /services/repository/target/apidocs/. Under ./ui/, open index.html in browser:

The spec itself can be found at /services/repository/target/apidocs/ui/swagger.json.

Some issues:

• Model definitions seem to be duplicated — for example, the schema for json_AccessApproval appears at both line 270 and line 16401. Because there are a lot of models in the Synapse API, this means a lot of extraneous lines of code in the spec.
• The documentation for various paths and operations often include HTML links to a webpage with details about a particular object (rather than a reference to the model definition within the spec).
• Probably others...