Follow the steps below to start designing an API:
- Log in to the API Publisher ( http://localhost:9763/publisher ) as a user who is assigned the creator role.
- Click Add to open Design API window as follows:
The sections below explain the fields of the above window.
General details
Field Description Name* Name of API as you want it to appear in the API store (E.g., PhoneVerification) Context* URI context path that is used by API consumers. (E.g., /phoneverify) Version* API version in the form of version.major.minor. (E.g., 1.0.0) Visibility See API visibility Tags Any number of tags separated by comma. Tags allow you to group/categorize APIs that have similar attributes and behaviors. When tagging, always use relevant keywords and common search terms. Once a tagged API gets published to the API Store, its tags appear on the dashboard as links to the API consumers, who can click on them to quickly jump to a category they are interested in. Resources See API Resources. (E.g., phoneID) API visibility
Visibility settings prevent certain user roles from viewing and modifying APIs created by another user role. The visibility values mean the following:- Public : The API is visible to all users (subscribers and anonymous users) of its tenant store. Also, the API can be advertised in multiple stores - a central store and/or non-WSO2 stores.
- Visible to my domain : The API is visible to all users who are registered in the API's tenant domain.
Restricted by Roles : The API is visible only to specific user roles in the tenant store. When
Restricted by Roles
is selected, a new field called Visible to Roles appears where you can specify the user roles that have access to the API in a comma-separated list (no spaces).
Given below is how visibility levels work for users in different tenant modes:
Visibility in super tenant mode
Subscribers in super tenant mode can see an API depending on its visibility level as follows:
- Anonymous users : can see APIs with
Public
visibility
- Signed-up users : can see all APIs with
Public
visibility as well as APIs that areRestricted by Roles
, give that the user is assigned to the role the API is restricted by.
Visibility in multi-tenant mode
In multi tenant environment, a subscriber can see API Store URLs of existing tenants. Click a URL to browse the tenant's API Store.
A tenant's API Store is the API Store specific to the tenant domain the user belongs to. You can also access it with the URL
http://<hostname>/Store?tenant=<tenantdomain.com>
. Therefore, the APIs a subscriber sees in multi tenant mode depend on their visibility levels as well as which API Store s/he is looking at. Any subscriber viewing his/her tenant's API Store can see an API depending on its visibility level as follows:- Anonymous users: can see APIs that have
Public
visibility and created within the current user's tenant domain
- Logged in users: can see,
- APIs that have
Public
visibility and created within the current users tenant domain
-
Restricted by Roles
APIs created within the current user's tenant domain and are allowed to be accessed by the role of the current user
- APIs that have
API resources
An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API.
API resources can accept the following attributes:Attribute name Description URL Pattern A URL pattern can be one of the following types:
- As a url-mapping. E.g.,
/state/town/*
- As a uri-template. E.g.,
/{state}/{town}
The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:
<resource methods="POST GET" url-mapping="/state/town/*"> <resource methods="POST GET" uri-template="/{state}/{town}">
url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching.
Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of
state
totexas
and the value oftown
tohouston
. You can use these parameters within the synapse configuration for various purposes and gain access to these property values through theuri.var.province
anduri.var.district
properties. For more information on how to use these properties, see Introduction to REST API and the HTTP Endpoint of the WSO2 ESB documentation.Also see http://tools.ietf.org/html/rfc6570 on URI templates.
HTTP Verb The HTTP methods that specify the desired action to be performed on the resource. These methods can be GET, POST, PUT, DELETE or OPTIONS. Multiple methods can be selected. Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the back-end is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The default in-sequence, out-sequence and fault sequences are generated when the API is published.
After providing all design details, click Implement at the bottom of the above UI to start implementing the API.