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
Maximilian Huber edited this page Jan 10, 2018 · 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)
  • REST API Gateway (subproject resource-server)

API 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):
 [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":"all","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":"all","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): all
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