Designing APIs

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).
- Roles that have API creation and publication permission can see all APIs in their tenant store even if you restrict access to them. This is because any role that has API creation and publication permission can view and edit all APIs in the API Publisher. Therefore, there is no reason to hide the APIs from them in the Store.
- If you restrict the default subscriber role under the Visible to Roles category, any user who self subscribes to the API Store will be able to access the API. This is because the API Manager assigns the subscriber role to all users who sign up to the API Store.

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 are Restricted 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

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 to texas and the value of town to houston. You can use these parameters within the synapse configuration for various purposes and gain access to these property values through the uri.var.province and uri.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.