Skip to content
This repository has been archived by the owner on Jul 25, 2018. It is now read-only.

REST API

Jump to bottom
Thomas Maier edited this page Dec 1, 2017 · 7 revisions

Introduction

The sw360REST API provides access to project resources for external clients.

Please note the state of the REST API is experimental and its may exposed by breaking changes.

Project structure

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

API Principles

The REST API provides Hypermedia using http://stateless.co/hal_specification.html[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): [source, json] { "_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 } ] } }

How to use it

Current endpoints: Actually the rest API uses the following application context paths:

(Authorization-Server) https://localhost:8443/authorization/oauth/authorize https://localhost:8443/authorization/oauth/check_token https://localhost:8443/authorization/oauth/token alternative http://localhost:8080/authorization/oauth/token

(Resource-Server) https://localhost:8443/resource/api/licenses https://localhost:8443/resource/api/projects https://localhost:8443/resource/api/components .... alternative http://localhost:8080/resource/api/licenses

Generate Access Token: You can generate the oauth2 access token by calling the following endpoint address. It is necessary to use the HTTP basic authentication and the Liferay credentials for the grant type:

e.g. (http):
curl -X POST --user 'trusted-sw360-client:sw360-secret' -d 'grant_type=password&username=<LIFERAY-USER-LOGIN>&password=<LIFERAY-USER-PASSWORD>' http://localhost:8080/authorization/oauth/token
   Response: {"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoiYWRtaW5Ac3czNjAub3JnIiwic2NvcGUiOlsic3czNjAucmVhZCIsInN3MzYwLndyaXRlIl0sImV4cCI6MTUxMTgxNDUyNSwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TVzM2MF9VU0VSIl0sImp0aSI6IjcyYWIxOGRlLWQ1NmQtNDM2OS1iNmFlLWEwYWViZDE1MDg0NiIsImNsaWVudF9pZCI6InRydXN0ZWQtc3czNjAtY2xpZW50In0.e3biYixvg8UZrLVxP4ts_jNemyaCkdVq9s0d1NCExrSN_UaX0wX085RUJqLL43aRi8ZelsgUjSqp0eR9ev5jObFZ5nRqRRwnTBpi9RmGfOxxav9Vjq8DOLAf7sQzIR2CFFtBIcC-WLGwKYcQoUrk6zyux7BxgdxdLp4WNx_ERz0Nx1uazrz4UieIRKXZ474AKAXbx9Q5gwC-uYSx6HHcePHV7TTeFCQYEN7zG9yCJsabr6nZSaflNVw8KE2Ot0nMiUF6QDRST4Nh6-aLFAHkV59dKOXjTdeZC760RpdSXbm_0XLL9aFTtdgEMiZc2B2iSFjY-XcMJJqmYlesLKVMBw","token_type":"bearer","expires_in":3599,"scope":"sw360.read sw360.write","jti":"72ab18de-d56d-4369-b6ae-a0aebd150846"}

e.g. (https):
curl -X POST --user 'trusted-sw360-client:sw360-secret' -d 'grant_type=password&username=<LIFERAY-USER-LOGIN>&password=<LIFERAY-USER-PASSWORD>' https://localhost:8443/authorization/oauth/token
   Response: {"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoiYWRtaW5Ac3czNjAub3JnIiwic2NvcGUiOlsic3czNjAucmVhZCIsInN3MzYwLndyaXRlIl0sImV4cCI6MTUxMTgxNDUyNSwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TVzM2MF9VU0VSIl0sImp0aSI6IjcyYWIxOGRlLWQ1NmQtNDM2OS1iNmFlLWEwYWViZDE1MDg0NiIsImNsaWVudF9pZCI6InRydXN0ZWQtc3czNjAtY2xpZW50In0.e3biYixvg8UZrLVxP4ts_jNemyaCkdVq9s0d1NCExrSN_UaX0wX085RUJqLL43aRi8ZelsgUjSqp0eR9ev5jObFZ5nRqRRwnTBpi9RmGfOxxav9Vjq8DOLAf7sQzIR2CFFtBIcC-WLGwKYcQoUrk6zyux7BxgdxdLp4WNx_ERz0Nx1uazrz4UieIRKXZ474AKAXbx9Q5gwC-uYSx6HHcePHV7TTeFCQYEN7zG9yCJsabr6nZSaflNVw8KE2Ot0nMiUF6QDRST4Nh6-aLFAHkV59dKOXjTdeZC760RpdSXbm_0XLL9aFTtdgEMiZc2B2iSFjY-XcMJJqmYlesLKVMBw","token_type":"bearer","expires_in":3599,"scope":"sw360.read sw360.write","jti":"72ab18de-d56d-4369-b6ae-a0aebd150846"}

Rest addon/plugin: The HAL-Browser is not a part of this pull request. But beside the HAL-Browser you can use several plugins/addons for Firefox or chrome. I recommend the postman addon (chrome). In postman you can directly authorize with oauth 2.0 to generate an access token.

postman1

Authorization settings:

Auth URL: https://localhost:8443/authorization/oauth/auhtorize
Access Token: https://localhost:8443/authorization/oauth/token?grant_type=password&username=<LIFERAY-USER>&password=<LIFERAY-USER-PW>
ClientID: trusted-sw360-client
ClientSecret: sw360-secret
Scope (optional): sw360.read sw360.write
Grant Type: Client Credentials

postman2

You can also use the access token as header parameter in your rest request. Please add a new header:

  • Key: Authorization
  • Value: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsic3czNjAtUkVTVC1BUEkiXSwidXNlcl9uYW1lIjoiYWRtaW5Ac3czNjAub3JnIiwic2NvcGUiOlsic3czNjAucmVhZCIsInN3MzYwLndyaXRlIl0sImV4cCI6MTUxMTgxMTU1NSwiYXV0aG9yaXRpZXMiOlsiUk9MRV9TVzM2MF9VU0VSIl0sImp0aSI6IjI4ZWI0ZTE0LTkzZGYtNDYxZC1iZjhhLTIwYjQ1OGQxOTc1OCIsImNsaWVudF9pZCI6InRydXN0ZWQtc3czNjAtY2xpZW50In0.Cbaqzyq6Yr7oM4Me0SSmeSbjypDZwHwOuJiVlZ4Ee98cdvyhCr7dI3ZV9-zKaiwrcnB9ERdJuoHcTOr1yMK8yvVlRMxwlkSE0QQvIyYUP0KIvR3ZuSTn25rl5inhBzy9usibJ9aQB4MMZOyhvoajuRWL09h0_Dx_gxjJDBMa8MNiNjXzIiF9s5YZbFPGlTaRWoXrTOZAvoUnJXlI_e6q9aMemLa7YGtSERte52LopAfRMpAmgiAJJD_NBijDFyozzhG2wlw6Xdk-B7wEfE7n2TjIhr05KXHYQcNeDhxScFGw_p9jInfm7-gy1q2rmoH_zlMcNedofGvz7uMewvLdew

As value you need to enter: "Bearer " + ACCESS_TOKEN

postman3

Clone this wiki locally