sw360 REST

Disclaimer

This project is will not longer continued here. Both the authorization server as well as the resource server are already integrated into the main portal project, see https://github.com/sw360/sw360portal/tree/master/rest

The client demo will probably also being integrated into the portal project later.

Overview

This project provides a REST API infrastructure for sw360, including

OAuth2 Authorisation Server (subproject authorization-server)
- This is for having an oauth2 provider 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" : "[email protected]",
      "_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" : "[email protected]",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/users/am9obkBzdzM2MC5vcmc="
        }
      }
    }, {
      "email" : "[email protected]",
      "_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 following 3 environment variables:

SW360_THRIFT_SERVER_URL to your local sw360 thrift server, including port, e.g. http://localhost:8080,
SW360_PORTAL_SERVER_URL to your local sw360 LifeRay portal server, including port, e.g. http://localhost:8080
SW360_LIFERAY_COMPANY_ID to the company id used in the LifeRay Portal

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 -Psw360args="<auth server URL>,<user>,<password>"
e.g. ./gradlew printAccessToken -Psw360args="http://192.168.99.100:8090,[email protected],sw360-admin-password"

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://<REST server URL>/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