Publisher APIs

Note that the contents on this page are deprecated. Click https://docs.wso2.com/display/AM1100/apidocs/publisher for the recommended list of Publisher APIs.

Publisher APIs provide the following REST resources.

Note: When you access any API other than the login and logout APIs through an external REST client such as cURL, first invoke the login API to ensure that user is authenticated. When the login API is invoked, the system stores the generated session cookie in a file, which we use in the next API invocations.

The responses is a JSON message.

Description	Log in to API Publisher web application.
URI	http://localhost:9763/publisher/site/blocks/user/login/ajax/login .jag
URI Parameters	action=login&username=xxx&password=xxx
HTTP Methods	POST
Example	curl -X POST -c cookies http://localhost:9763/publisher/site/blocks/user/login/ajax/login.jag -d 'action=login&username=admin&password=admin'

Logout

Description	Log out from API Publisher web application.
URI	http://localhost:9763/publisher/site/blocks/user/login/ajax/login .jag
URI Parameters	?action=logout
HTTP Methods	GET
Example	curl -b cookies http://localhost:9763/publisher/site/blocks/user/login/ajax/login.jag?action=logout

Add API

Description Add a new API.

URI http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag

URI Parameters

Given below are the parameters that you can pass with an Add-API call. Mandatory ones are marked with a *.

Parameter name	Syntax
Action*	action=addAPI
Name*	name=xxx
Context*	context=/xxx
Version*	version=x.x.x
API visibility*	visibility=<public\|private\|restricted> The default is public. If you select `restricted`, mention to which roles as follows: `visibility=restricted&roles=role1,role2,role3`. You can read more about API visibility from here.
Thumbnail image	To add a thumbnail image as a file object, create the object and pass it with the `apiThumb` parameter. See sample in this `getMultipartEntity()` method. To add a thumbnail image as a URL of the image, pass the URL with the `thumbUrl` parameter as thumbUrl=<URL of the image>
Description	description=xxx
Tags	tags=x,y,z
Resources*	resourceCount=0&resourceMethod-0=GET&resourceMethodAuthType-0=Application&resourceMethodThrottlingTier-0=Unlimited `resourceMethod` can take any one of the following values: GET, POST, DELETE, PUT, OPTIONS `resourceMethodAuthType` can take any one of the following values: Application, Application User, Application and Application User, None `resourceMethodThrottlingTier` can take any one of the following default values: Unlimited, Gold, Silver, Bronze. You can change the default values or have additional tiers defined in the `/_system/governance/apimgt/applicationdata/tiers.xml` registry location.
Resources as Swagger	Instead of adding resources directly as above, you can add resources, including scopes, as a Swagger payload. Here's an example of adding an API with its Swagger definition: swagger={"paths" : {"/CheckPhoneNumber" : {"post" : {"x-auth-type" : "Application%20%26%20Application%20User", "x-scope" : "read_number", "x-throttling-tier" : "Unlimited", "responses" : {"200" : {}}}, "get" : {"x-auth-type" : "Application%20%26%20Application%20User", "x-throttling-tier" : "Unlimited", "responses" : {"200" : {}}, "parameters" : [{"name" : "PhoneNumber", "paramType" : "query", "required" : false, "type" : "string", "description" : "Phone Number", "in" : "query"}, {"name" : "LicenseKey", "paramType" : "query", "required" : false, "type" : "string", "description" : "License Key", "in" : "query"}]}}, "/" : {"put" : {"responses" : {"200" : {}}}, "get" : {"responses" : {"200" : {}}}}}, "swagger" : "2.0", "x-wso2-security" : {"apim" : {"x-wso2-scopes" : [{"description" : "", "name" : "read_number", "roles" : "admin", "key" : "read_number"}]}}, "info" : {"title" : "PhoneVerification", "version" : "1.0.0"}} In the above code, note that you have one resource path defined with the URL pattern `/CheckPhoneNumber` under the `paths` object. This is followed by the HTTP methods of the resource (e.g., GET, POST, PUT etc.) You can have multiple similar resource paths to a single API and multiple HTTP methods to each resource path. For each HTTP method, you can define several parameters. For more information of the Swagger objects used in this example, see the Swagger 2.0 specification. Described below are the WSO2-specific ones. x-wso2-scopes: The list of scope elements that you want to define. Each element has the below fields. See OAuth Scopes. description: Scope description roles: Allowed roles name: Scope Name key: Scope Key x-auth-type: Authentication type of the method. x-throttling-tier: Throttling tier of the method. x-scope: OAuth scope of the method. This must be one of the list of element you define in x-wso2-scopes. The following image shows the WSO2-specific parameters we describe here. Also see Resources under Key Concepts for more information.
Endpoints*	This example adds an HTTP production endpoint: `endpoint_config={"production_endpoints":{"url":"<URL>","config":{"format":"leave-as-is","optimize":"leave-as-is","actionSelect":"fault","actionDuration":60000}},"endpoint_type":"http"}` To give advanced endpoint configurations, add the JSON implementation inside "config:{}." If you don't have any advanced configurations, set it to null as `"config":null`. You add sandbox endpoints in the same way. The only difference is that instead of `production_endpoints`, you give `sandbox_endpoints`. If you want to add other types of endpoints, follow the examples below. Note that the `endpoint_type` of of both HTTP and HTTPS endpoints should be HTTP. For address endpoints: `endpoint_config={"production_endpoints":{"url":"http://service.endpoint.com","config":null},"endpoint_type":"address"}` For failover endpoints: `endpoint_config={"production_endpoints":{"url":"http://service.endpoint.com","config":null}, "production_failovers":{"url":"http://failover1.endpoint.com","config":null}, {"url":"http://failover2.endpoint.com","config":null}],"sandbox_failovers":[],"endpoint_type":"failover"}` For load balanced endpoints: `endpoint_config" {"production_endpoints":[{"url":"http://service.endpoint1.com","config":null},{"url":"http://service.endpoint2.com","config":null}], "algoCombo":"org.apache.synapse.endpoints.algorithms.RoundRobin","failOver":"True", "algoClassName":"org.apache.synapse.endpoints.algorithms.RoundRobin", "sessionManagement":"simpleClientSession","sessionTimeOut":30,"endpoint_type":"load_balance"}`
Endpoint security scheme	endpointType=<secured\|nonsecured> The default is non-secured but if you select 'secured', you must pass the credentials as follows: `endpointType=secured&endpointAuthType=<basicAuth\|digestAuth>&epUsername=<your username>&epPassword=<the password>`
Make default version	To mark this version of the API as the default version from a group of versions, give `default_version_checked=default_version`. The Default Version option means that you make this version the default in a group of different versions of the API. A default API can be invoked without specifying the version number in the URL. For example, if you mark http://host:port/youtube/2.0 as the default version when the API has 1.0 and 3.0 versions as well, requests made to http://host:port/youtube/ get automatically routed to version 2.0. If you mark any version of an API as the default, you get two API URLs in its Overview page in the API Store. One URL is with the version and the other is without. You can invoke a default version using both URLs. If you mark an unpublished API as the default, the previous default, published API will still be used as the default until the new default API is published (or prototyped).
Tier Availability*	tiersCollection=<Gold,Silver,Bronze,Unlimited>
Transports	http_checked=http&https_checked=https Both are selected by default. If you want to set only the HTTP transport, leave the `https_checked` parameter empty as `http_checked=http&https_checked=&`.
Sequences	If you want to engage a custom sequence to the API, give `inSequence=<sequence name>&outSequence=<sequence name>`. This tutorial explains how to create sequences and add them to the registry.
Response caching	responseCache=<enabled\|disabled> It is disabled by default but if you enable it, pass the response cache timeout as follows: `responseCache=enabled&cacheTimeout=300` See Configuring Caching for more information.
Subscriptions	By default, subscription is allowed to the current tenant only. Add the argument `subscriptions=all_tenants` to enable subscriptions to this API by all tenants. To enable subscription to selected tenants, use `subscriptions=specific_tennats&tenants=<tenant name>`. For example, `&subscriptions=all_tenants`. See API visibility and subscription for more information.
Business information	Add a section like this: `bizOwner=<name>&bizOwnerMail=<e-mail address>&techOwner=<name>&techOwnerMail=<e-mail address>`

HTTP Methods POST

Example

curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag -d "action=addAPI&name=PhoneVerification&context=/phoneverify&version=1.0.0&visibility=public&thumbUrl=&description=Verify a phone number&tags=phone,mobile,multimedia&endpointType=nonsecured&tiersCollection=Gold,Bronze&http_checked=http&https_checked=https&resourceCount=0&resourceMethod-0=GET&resourceMethodAuthType-0=Application&resourceMethodThrottlingTier-0=Unlimited&uriTemplate-0=/*&default_version_checked=default_version&bizOwner=xx&bizOwnerMail=xx@ee.com&techOwner=xx&techOwnerMail=ggg@ww.com" -d'endpoint_config={"production_endpoints":{"url":"http://ws.cdyne.com/phoneverify/phoneverify.asmx","config":null},"endpoint_type":"http"}';

Add API with Path Parameter

Description	Add a new API with path parameter
URI	http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag
URI Parameters	action=addAPI&name=xxx&context=/xxx&version=1.0.0&visibility=xxx&thumbUrl=&description=xxx&tags=xxx&endpointType=xxx&tiersCollection=xxx&http_checked=http&https_checked=https" -d 'swagger=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag -d "action=addAPI&name=SampleApi&context=/sample&version=1.0.0&visibility=public&thumbUrl=&description=Verify a phone number&tags=phone,mobile,multimedia&endpointType=nonsecured&tiersCollection=Gold,Bronze&http_checked=http&https_checked=https" -d 'swagger={"paths" : {"/estimate/" : {"get" : {"x-auth-type" : "Application%20%26%20Application%20User", "x-throttling-tier" : "Unlimited", "responses" : {"200" : {}}, "parameters" : [{"name" : "id", "paramType" : "path", "required" : false, "type" : "string", "description" : "Phone Number", "in" : "path"}]}}}, "swagger" : "2.0", "x-wso2-security" : {"apim" : {"x-wso2-scopes" : [{"description" : "", "name" : "read_number", "roles" : "admin", "key" : "read_number"}]}}, "info" : {"title" : "SampleApi", "version" : "1.0.0"}}' -d'endpoint_config={"production_endpoints":{"url":"http://ws.cdyne.com/phoneverify/phoneverify.asmx","config":null},"endpoint_type":"http"}

Update API

Description	Update an existing API
URI	http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag
URI Parameters	Parameters are same as in Add API except that action=updateAPI and you can only update the following parameters: visibility, thumbUrl, description, tags, endpointType, endpoint_config (can change the endpoint URL etc,) http_checked, https_checked, tiersCollection, swagger and can also add new resources. See example below.
HTTP Methods	POST
Example	Update API : curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag -d "action=updateAPI&name=PhoneVerification&provider=admin&version=1.0.0&visibility=public&description=Youtube Live Feeds&endpointType=nonsecured&http_checked=http&https_checked=https&tags=youtube,gdata,multimedia&tier=Silver&thumbUrl=http://www.10bigideas.com.au/www/573/files/pf-thumbnail-youtube_logo.jpg&context=/youtube&tiersCollection=Gold,silver&resourceCount=0&resourceMethod-0=GET&resourceMethodAuthType-0=Application&resourceMethodThrottlingTier-0=Unlimited&uriTemplate-0=/*" -d'endpoint_config={"production_endpoints":{"url":"http://gdata.youtube.com/feeds/api/standardfeeds","config":null},"endpoint_type":"http"}';

Get All APIs

Description	Lists all the created APIs.
URI	http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag
URI Parameters	?action=getAllAPIs
HTTP Methods	GET
Example	curl -b cookies http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag ?action=getAllAPIs

Get an API

Description	Get details of a specific API.
URI	http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag
URI Parameters	action=getAPI&name=xxx&version=xxx&provider=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/listing/ajax/item-list.jag -d "action=getAPI&name=PhoneVerification&version=1.0.0&provider=admin"

Remove an API

Description	Remove an API.
URI	http://localhost:9763/publisher/site/blocks/item-add/ajax/remove.jag
URI Parameters	action=removeAPI&name=xxx&version=xxx&provider=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/item-add/ajax/remove.jag -d "action=removeAPI&name=PhoneVerification&version=1.0.0&provider=admin"

Copy an API

Description	Copy an API to a newer version.
URI	http://localhost:9763/publisher/site/blocks/overview/ajax/overview.jag
URI Parameters	action=createNewAPI&provider=xxx&apiName=xxx&version=xxx&newVersion=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/overview/ajax/overview.jag -d "action=createNewAPI&provider=admin&apiName=PhoneVerification&version=1.0.0&newVersion=2.0.0&isDefaultVersion=default_version"

Check Older Version

Description	Does older version of API exist.
URI	http://localhost:9763/publisher/site/blocks/life-cycles/ajax/life-cycles.jag
URI Parameters	action=isAPIOlderVersionExist&provider=xxx&name=xxx&version=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/life-cycles/ajax/life-cycles.jag -d "action=isAPIOlderVersionExist&provider=admin&name=PhoneVerification&version=1.0.0"

Change API Status

Description	Change the API's status.
URI	http://localhost:9763/publisher/site/blocks/life-cycles/ajax/life-cycles.jag
URI Parameters	action=updateStatus&name=xxx&version=1.0.0&provider=apiCreateName&status=PUBLISHED&publishToGateway=true&requireResubscription=true
HTTP Methods	POST
Example	curl -X POST -b cookies 'http://localhost:9763/publisher/site/blocks/life-cycles/ajax/life-cycles.jag' -d 'action=updateStatus&name=PhoneVerification&version=1.0.0&provider=admin&status=PUBLISHED&publishToGateway=true&requireResubscription=true'

Add/Update an API Document

Description	Add a new API document.
URI	http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag
URI Parameters	Add Document: action=addDocumentation&provider=xxx&apiName=xxx&version=xxx&docName=xxx&docType=xxx&sourceType=xxx&docUrl=xxx&summary=xxx&docLocation=xxx&docVisibility=owner_only/private Note that docVisibility is applicable only if you have enabled it. See API documentation visibility. Add Document file: action=addDocumentation&provider=xxx&apiName=xxx&version=xxx&docName=xxx&docType=xxx&sourceType=xxx&docUrl=xxx&summary=xxx&docLocation=xxx Update Document: action=addDocumentation&mode=Update&provider=xxx&apiName=xxx&version=xxx&docName=xxx&docType=xxx&sourceType=xxx&docUrl=xxx&summary=xxx&docLocation=xxx
HTTP Methods	POST
Example	Add Document: curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag -d "action=addDocumentation&provider=admin&apiName=PhoneVerification&version=1.0.0&docName=testDoc&docType=how to&sourceType=inline&docUrl=&summary=testing&docLocation=" Add Document file: curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag -F "action=addDocumentation" -F "provider=admin" -F "apiName=testAPi" -F "version=1.0.0" -F "docName=testDoc2" -F "docType=how to" -F "sourceType=file" -F "docUrl=" -F "summary=testing" -F "docLocation=@test.txt" Update Document: curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag -d "action=addDocumentation&mode=Update&provider=admin&apiName=PhoneVerification&version=1.0.0&docName=testDoc&docType=how to&sourceType=inline&docUrl=&summary=new summary&docLocation="

Remove an API Document

Description	Remove an API document.
URI	http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag
URI Parameters	action=removeDocumentation&provider=xxx&apiName=xxx&version=xxx&docName=xxx&docType=xxx
HTTP Methods	POST
Example	curl -X POST -b cookies http://localhost:9763/publisher/site/blocks/documentation/ajax/docs.jag -d 'action=removeDocumentation&provider=admin&apiName=PhoneVerification&version=1.0.0&docName=testDoc&docType=How To'

Get all Throttling Tiers

Description	Get the throttling tiers that can be applied to APIs
URI	http://localhost:9763 /publisher/site/blocks/item-add/ajax/add.jag?
URI Parameters	action=getTiers
HTTP Methods	GET
Example	curl -b cookies http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag?action=getTiers

Check if API Exists

Description	Check if an API by a given name exists in the API Publisher
URI	http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag
URI Parameters	action=isAPINameExist&apiName=<name of the API>
HTTP Methods	GET
Example	curl -b cookies "http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag?action=isAPINameExist&apiName=PhoneVerification"

Validate Roles

Description	Check if the user logged in user is any one in a given list of users
URI	http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag
URI Parameters	action=validateRoles&roles=<list of roles>
HTTP Methods	GET
Example	curl -b cookies "http://localhost:9763/publisher/site/blocks/item-add/ajax/add.jag?action=validateRoles&roles=admin"