1. Publisher Jax-RS web application
The JaxRS REST API web application which is responsible for all Publisher web app related functions.
2. Store Jax-RS web application
The JaxRS REST API web application which is responsible for all Store web app related functions.
3. Client-Registration Jax-RS web application
The JaxRS REST API web application which is responsible for creating OAuth applications in order to access Store or Publisher REST APIs.
Invoke DCR and create an OAuth Application
For this step you can also refer API Manager REST API documentation [1], but I will state the basic steps in brief.As the first step you have to invoke the client-registration API. This is a new JaxRS web app, introduced in API Manager 1.10.0 version to create OAuth applications to invoke the new REST API. It has initial version of v0.9.
The API is secured with Basic authentication so you need to provide base64encoded(username:password) as the Authorization: Basic header.
curl -X POST -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d @payload.json http://localhost:9763/client-registration/v0.9/register
Sample payload.json file:
{
"callbackUrl": "www.google.lk",
"clientName": "rest_api_publisher",
"tokenScope": "Production",
"owner": "admin",
"grantType": "password refresh_token",
"saasApp": true
}
In this payload you specify "clientName" which is the OAuth application name.After sending the above request you will get a response like this:
HTTP/1.1 201 Created
Date: Sun, 20 Mar 2016 03:29:57 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Server: WSO2 Carbon Server
{
"jsonString":"{\"username\":\"admin\",\"redirect_uris\":\"www.google.lk\",\"client_name\": \"admin_rest_api_publisher\",\"grant_types\":\"urn:ietf:params:oauth:grant-type:saml2-bearer iwa:ntlm implicit refresh_token client_credentials authorization_code password\"}",
"appOwner":null,
"clientName":null,
"callBackURL":"www.google.lk",
"isSaasApplication":true,
"clientId":"xe94b1qreLVlplHjZGwLtfrmv38a",
"clientSecret":"fOua2cfsdTowN0apzCcJ2uIfLMYa"
}
Now you have successfully created an OAuth application. Now you can invoke the Token API [2] to create an access token using the received client ID and client Secret. This is exactly same as when you invoke token API to create an access token to invoke an API published in API Manager.
This supports all OAuth2 grant types that API Manager supports and here I am using password grant type to create an access token.
curl -k -d "grant_type=password&username=admin&password=admin&scope=<scopes>" -H "Authorization: Basic <base64encoded(clientid:clientsecret)> https://127.0.0.1:8243/token
Scopes
One thing to note here is the scope field. In new REST API there is a specific scope mapped to resource verb combinations. For example if you need to invoke Get All APIs in Publisher REST API, your token need to have apim:api_view scope.The REST API consists of following OAuth scopes. As an API creator, publisher or subscriber you need to have access to following set of scopes:
As an API Creator:
- apim:api_view - to view APIs
- apim:api_create - to create new APIs
- apim:subscription_view - to view subscriptions of APIs
- apim:subscription_block - to block/unblock subscription of APIs
- apim:tier_view - to view tiers
- apim:api_view - to view APIs
- apim:api_publish - to change lifecycle states of APIs (publish, deprecate, retire APIs etc)
- apim:api_subscribe - create applications, view applications, subscribe to APIs and all Store related operations
- ++ all creator scopes
- ++ all publisher scopes
- ++ all subscriber scopes
- apim:tier_manage - to block unblock subscribing to tiers in Store based on user's roles
Tip
--------
You can just try asking for an invalid random scope and check what you receive.
curl -k -d "grant_type=password&username=admin&password=admin&scope=random_invalid_scope"
-H "Authorization: Basic eGU5NGIxcXJlTFZscGxIalpHd0x0ZnJtdjM4YTpmT3VhMmNmc2RUb3dOMGFwekNjSjJ1SWZMTVlh"
https://127.0.0.1:8243/token -v
Response:
< HTTP/1.1 200 OK
< Content-Type: application/json
< Pragma: no-cache
< Cache-Control: no-store
< Date: Sun, 20 Mar 2016 07:14:59 GMT
< Transfer-Encoding: chunked
<
* Connection #0 to host 127.0.0.1 left intact
{"scope":"default","token_type":"Bearer","expires_in":3600,"refresh_token":"1e2f7d03297f51b2bf4b0762efa9546a",
"access_token":"081f892624caeb3be2b1a1ab22b00316"}
You can see you receives an scope called default but not what you requested.
--------
You can request single or many scopes at once. When requesting multiple scopes you need to give them space separated.
Let's request all scopes related to an API creator. See the sample curl command below.
curl -k -d "grant_type=password&username=admin&password=admin&scope=apim:api_view apim:api_create apim:subscription_view apim:subscription_block apim:tier_view" -H "Authorization: Basic eGU5NGIxcXJlTFZscGxIalpHd0x0ZnJtdjM4YTpmT3VhMmNmc2RUb3dOMGFwekNjSjJ1SWZMTVlh" https://127.0.0.1:8243/token -v
You will receive following response:
< HTTP/1.1 200 OK
< Content-Type: application/json
< Pragma: no-cache
< Cache-Control: no-store
< Date: Sun, 20 Mar 2016 07:09:41 GMT
< Transfer-Encoding: chunked
<
* Connection #0 to host 127.0.0.1 left intact
{"scope":"apim:api_create apim:api_view apim:subscription_block apim:subscription_view apim:tier_view",
"token_type":"Bearer","expires_in":3600,"refresh_token":"dc760c94e3c8a5c4c3d263b14708b275","access_token":"fb3db536b07f2a1da0185d82b0887848"}
You can see you received all scopes you requested - "scope":"apim:api_create apim:api_view apim:subscription_block apim:subscription_view apim:tier_view" .
Before going further you have to make sure you have received the scopes you requested.
Invoking a sample API
Now we are done with getting an access token. Lets try to invoke an API in Publisher.An easiest API for a beginner is Get All Tiers API as it does not require any prerequisites. See that API in documentation [3]
Request path : https://localhost:9443/api/am/publisher/v0.9/apis/tiers/api
Request HTTP method : GET
Scope : apim:tier_view
Use the following curl command. Replace the access token with what you received from token API. Lets use the access token we got from invoking the token API. We have to use it as Authorization: Bearer header. Just same as when we invoke an API published in API Manager.
curl -k -H "Authorization: Bearer fb3db536b07f2a1da0185d82b0887848" https://127.0.0.1:9443/api/am/publisher/v0.9/tiers/api -vYou will be able to see following response.
< HTTP/1.1 200 OK
< Date: Sun, 20 Mar 2016 08:19:56 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: WSO2 Carbon Server
<
* Connection #0 to host 127.0.0.1 left intact
{
"previous":"",
"list":[
{
"unitTime":60000,
"tierPlan":"FREE",
"tierLevel":"api",
"stopOnQuotaReach":true,
"requestCount":1,
"description":"Allows 1 request(s) per minute.",
"name":"Bronze",
"attributes":{
}
},
{
"unitTime":60000,
"tierPlan":"FREE",
"tierLevel":"api",
"stopOnQuotaReach":true,
"requestCount":20,
"description":"Allows 20 request(s) per minute.",
"name":"Gold",
"attributes":{
}
},
{
"unitTime":60000,
"tierPlan":"FREE",
"tierLevel":"api",
"stopOnQuotaReach":true,
"requestCount":5,
"description":"Allows 5 request(s) per minute.",
"name":"Silver",
"attributes":{
}
},
{
"unitTime":0,
"tierPlan":null,
"tierLevel":"api",
"stopOnQuotaReach":true,
"requestCount":0,
"description":"Allows unlimited requests",
"name":"Unlimited",
"attributes":{
}
}
],
"count":4,
"next":""
}
References:
[1] https://docs.wso2.com/display/AM1100/apidocs/publisher/index.html#guide[2] https://docs.wso2.com/display/AM1100/Token+API
[3] https://docs.wso2.com/display/AM1100/apidocs/publisher/index.html#!/operations#TiersApi#tiersTierLevelGet
No comments:
Post a Comment