An API creator uses the API provider Web application to create and publish APIs into the API Store. In this section, we explain how to create an API and attach documentation to it.
The Phone Number Validation API
Along In this guide, we work with a service exposed by the Cdyne services provider (www.wdyne.com). We use their phone validation service, which has SOAP and REST interfaces and is documented using a WSDL file. This service is documented at : http://wiki.cdyne.com/index.php/Phone_Verification.
- Open the API Publisher (
https://<YourHostName>:9443/publisher) and log in as
Click the Add link and provide the mandatory information, as described in the table below, to your API.
Field Value Description NamePhoneVerificationName of API as you want it to appear in the APIstoreContext/phoneverifyURI context path that is used by to API consumers Version 1.0.0 API version (in the form of version.major.minor) Description Text High level description of API functionality Visibility Public/RestrictedIf the API can be accessed by everyone, then select the visibility as 'Public'. Else select it as 'Restricted' and enter the user roles to which the API can be accessiblefrom both API publisher and store.Thumbnail Image Image file Icon to be displayed in API store (can be jpeg, tiff, png format)Tier Availability Bronze/Gold/Silver/Unlimited The API can be available at different level of service; you can select multiple entries from the list. At subscription time, the consumer chooses which tier they are interested in. Transports Select HTTP/HTTPSEndpoint Security SchemeNon-Secured/SecuredIf the back-end service is a secured service, select 'Secured' and enter the credentials for secured service in appearing text boxes. Else keep as Non-Secured. Endpoint Type SelectEndpoint Type. E.g., High available and load balanced endpoints Production URLEndpoint URLEndpoint of the back-end service URL, here: Sandbox URLEndpoint URLEndpoint of sandbox (testing) back end service. A sandbox URL is meant to be used for online testing of an API with easy access to an API key. WSDL URLURL of WSDL file (describing API interface) http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl WADL URL URL to WADL file (describing API interface) Tags StringOne of more tags separated by comma. Tags are used to group/search for API. Tier AvailabilityBronze/Gold/Silver/UnlimitedThe API can be available at different level of service; you can select multiple entries from the list. At subscription time, the consumer chooses which tier they are interested in.Business Owner and Email StringInformation about the person responsible for this API at the business level Technical Owner Email StringInformation about the person responsible for this API at the technical level
Adding API resources
An API is made up of one or more resources. Each resource handles a particular type of requests. A resource is analogous to a method (function) in a larger API.
API resources accept following attributes:
- Verbs: HTTP verbs a particular resource accepts. Allowed values are GET, POST, PUT, DELETE. Multiple values can be specified.
- URL pattern: URI template as defined in http://tools.ietf.org/html/rfc6570. E.g.,
- Auth type: Resource level authentication along HTTP verbs. Can be one of the following:
- None : Can access the API resource without any access tokens
- Application: Application access token is required to access the API resource
- Application User: User access token is required to access the API resource
Once a request is accepted by a resource, it is mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either in or our sequences. Default in-sequence, out-sequence and fault sequence are generated when the API is published.
After creating the API, click on its icon to open its details. Select the Docs tab, For example,
Click Add New Document link.Documentation can be provided inline, via a URL or as
- a file. For inline documentation, you can edit the content directly from the API publisher interface. You get several documents types:
- Swagger documents
- How To
- Samples and SDK
- Public forum / Support forum (external link only)
- API message formats