sw360 REST

Disclaimer

This project is in a very early stage, mainly starting a proof of concept for a possible REST API for the sw360 portal.

Please stay tuned…​

Overview

This project provides a REST API infrastructure for sw360, including

• OAuth2 Authorisation Server (subproject authorization-server)

  • This is just for having an oauth2 provider for testing authorization

  • Might be replaced in the future

• REST API Gateway (subproject resource-server)

  • Currently in experimental phase to find out what the best mapping to the existing sw360 domain model would be

• Docker Sandbox (subproject docker-sandbox)

  • This is a minimal docker setup for testing the REST API, it is not supposed to be used in production

  • It contains 4 containers

    • CouchDB

    • sw360 Thrift server

    • OAuth2 Authorisation Server

    • sw360 REST API Gateway

• Demo client application (subproject demo-app)

  • It is planned to provide blueprints for common use cases here

  • Currently it only contains a demo app that sets up test data for the docker sandbox

API Design Principles

The REST API provides Hypermedia using HAL (Hypertext Application Language). The following examples show some ideas of the REST API. As mentioned above, this is NOT the final API, it is just a base for discussion.

API root (index):

{
  "_links" : {
    "sw360:attachments" : {
      "href" : "http://localhost:8080/api/attachments{?sha1}",
      "templated" : true
    },
    "sw360:components" : {
      "href" : "http://localhost:8080/api/components"
    },
    "sw360:projects" : {
      "href" : "http://localhost:8080/api/projects"
    },
    "sw360:releases" : {
      "href" : "http://localhost:8080/api/releases"
    },
    "sw360:users" : {
      "href" : "http://localhost:8080/api/users"
    },
    "profile" : {
      "href" : "http://localhost:8080/api/profile"
    },
    "curies" : [ {
      "href" : "http://localhost:8080/docs/html5/{rel}.html",
      "name" : "sw360",
      "templated" : true
    } ]
  }
}

When you follow the link "sw360:components" you will get a list of components, each containing the basic set of information and a self link to the actual component resource, e.g.

{
  "_embedded" : {
    "sw360:components" : [ {
      "type" : "component",
      "name" : "Angular",
      "componentType" : "OSS",
      "createdOn" : "2016-12-15",
      "vendorNames" : [ "Google" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/components/17653524"
        }
      }
    }, {
      "type" : "component",
      "name" : "Spring Framework",
      "componentType" : "OSS",
      "createdOn" : "2016-12-18",
      "vendorNames" : [ "Pivotal" ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/components/678dstzd8"
        }
      }
    } ]
  },
  "_links" : {
    "curies" : [ {
      "href" : "http://localhost:8080/docs/html5/{rel}.html",
      "name" : "sw360",
      "templated" : true
    } ]
  }
}

When you follow one of the components’s self links, you will get more detailed information, including a description, embedded releases and moderators, e.g.

{
  "type" : "component",
  "name" : "Angular",
  "componentType" : "OSS",
  "description" : "Angular is a development platform for building mobile and desktop web applications.",
  "createdOn" : "2016-12-15",
  "vendorNames" : [ "Google" ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/components/17653524"
    }
  },
  "_embedded" : {
    "createdBy" : {
      "email" : "admin@sw360.org",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/users/YWRtaW5Ac3czNjAub3Jn"
        }
      }
    },
    "releases" : [ {
      "version" : "2.3.0",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/releases/3765276512"
        }
      }
    }, {
      "version" : "2.3.1",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/releases/3765276512"
        }
      }
    } ],
    "moderators" : [ {
      "email" : "john@sw360.org",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/users/am9obkBzdzM2MC5vcmc="
        }
      }
    }, {
      "email" : "admin@sw360.org",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/users/YWRtaW5Ac3czNjAub3Jn"
        }
      }
    } ]
  }
}

REST API Documentation

You find the current REST API documentation at https://s3.amazonaws.com/sw360restdoc/api-guide.html

The documentation was created with Spring REST Docs and reflects the current implementation. It is updated automatically with each Travis-CI build.

Getting Started

Before you can build and run all the tests, make sure that you have

• Java 8 SDK installed

• Build the sw360 portal project locally (https://github.com/sw360/sw360portal)

  • datahandler-1.6.0-SNAPSHOT.jar has to be in your local maven repository

To build an run all tests open a console and type

• Linux/Mac: ./gradlew build

• Windows: gradlew build

In the following description I use "./gradlew", Windows users always just have to type "gradlew" instead.

Creating a Docker sandbox

Preconditions:

• docker and docker-compose installed

• Local maven build of the sw360 portal project

To create the Docker sandbox, invoke

• ./gradlew build preparedocker

• docker-compose build

• docker-compose up

• Check/Modify the IP address in the DemoApplication and run it

• Browse to <docker-host>:8091/browser.html#/api

  • This version of the HAL browser contains a oauth2 bearer token for the docker sandbox

The docker-sandbox does not contain any test data yet. To fill it with test data, do the following steps (will be more automated in the future):

• Download https://repo.spring.io/release/org/springframework/spring/4.3.5.RELEASE/spring-framework-4.3.5.RELEASE-dist.zip

• Unzip it

• Modify class DemoApplication subprojects/demo-app:

  • DOCKER_HOST to your docker host

  • SPRING_FRAMEWORK_DIST to your unzipped Spring framework dist

• Run class DemoApplication

Browsing existing sw360 portal data with the sw360 REST API

This is currently work in progress and will be easier in the future.

The precondition for browsing the real sw360 data using the REST API is that you have all the sw360 Thrift services running. You could change the Thrift services URL by setting the environment variable SW360_THRIFT_SERVER_URL to your local sw360 thrift server, e.g. http://localhost:8080 or you could edit edit subprojects/resource-server/src/main/resources/application.yml. The default configuration is:

sw360:
  thrift-server-url: ${SW360_THRIFT_SERVER_URL:http://localhost:8080}

Furthermore you need to configure the hardcoded sw360 user id in the authorization server to match the id/email of an existing sw360 user. To do that, edit the values for sw360.test-user-id in subprojects/authorization-server/src/main/resources/application.yml. The defaults are:

sw360:
  test-user-id: admin@sw360.org
  test-user-password: sw360-admin-password

Right now you have to start both the authorization server as well as the resource server in 2 separate console windows:

• ./gradlew authorization-server:bootrun

  • starts the authorization server at localhost:8090

• ./gradlew resource-server:bootrun

  • starts the resource server at localhost:8091

Then get an oauth2 token from the authorization server by running

• ./gradlew printAccessToken

At the end of the console output you will get something like:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoic3czNjAtdXNlciIsInNjb3BlIjpbInN3MzYwLnJlYWQiLCJzdzM2MC53cml0ZSJdLCJleHAiOjE0ODE2MjQyOTYsImF1dGhvcml0aWVzIjpbIlJPTEVfU1czNjBfVVNFUiJdLCJqdGkiOiIzMDgyMDM5ZS0xY2ViLTQ5ZDktYWM1My0xMzIxMTNhMWQwMDQiLCJjbGllbnRfaWQiOiJ0cnVzdGVkLXN3MzYwLWNsaWVudCJ9.Exm2Yc-XaTff6FrGRTL4lXhBvbAD05XH8sTFC1kPRuqPkWqW2T0IgMgOs7iNDFwREvnqhAP4ZkCEFWYy-kiGU63HDlobDntJkJqvZjLTBlv4jOlXXJQ0TZWm6c-ochNWMkKI2tYO8EeDLqHj0jW1DWQ1I3o6cVtYdJ-etwOuIAP0uC9sykHlJkL_-TjvGpxpPXj_gTzeuvvOtqqhgF10uOpN-BBq5nLyRP4Zgrd1NhE-E6osb8xZrzn0WjtHA5ja62lmJ-a40sQ2kaXP8pik4pq3hmv2yNDK0TExjvvDXS_aEEavUv1p2-LmlyTua2UizHHxLxFjqptE2FqMZlmqkQ

Then open the following URL in a web browser: http://localhost:8091/api/browser/index.html#/api

Now you should see an API browser (Hal-Browser), but you are not authorized yet. Copy the whole token (including "Authorization: Bearer") into the "Custom Request Headers" field in the HAL-Browser and click on the "Go!" button.

Now you are authorized and can use the HAL-Browser to navigate through the API.

License

SPDX Short Identifier: http://spdx.org/licenses/EPL-1.0

All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html