Versions Compared

Old Version 25

changes.mady.by.user Former user

Saved on

compared with

New Version 26

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

An API creator uses the API Publisher to create and publish APIs to the API Store. Let's create an API and add interactive Swagger-based documentation to it. 

In this guide, we work with a service exposed by the Cdyne services provider (www.cdyne.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.

  1. Open the API Publisher (https://<hostname>:9443/publisher) and log in as apicreator.

  2. Click the Add link and provide the information given in the table below. Click Implement once you are done.

    Field Sample value
    Name 
    PhoneVerification
    Context
    		 
    /phoneverify
    Version 1.0.0
    Visibility Public
    ResourcesURL patternCheckPhoneNumber
     Request typesGET, POST, OPTIONS

  3. Give the following information in the Implement tab that opens and click Manage once you are done.

    FieldSample value
    Implementation methodBackend
    Endpoint typeHTTP
    Production endpoint

    This sample service has two operations as CheckPhoneNumber and CheckPhoneNumbers. Let's use CheckPhoneNumber here.
    In this guide, we work with a service exposed by the Cdyne services provider. We use their phone validation service, which has SOAP and REST interfaces. Endpoint is http://ws.cdyne.com/phoneverify/phoneverify.asmxTo verify the URL, click the Test button next to it. 

    This sample service has two operations as CheckPhoneNumber and CheckPhoneNumbers. Let's use CheckPhoneNumber here.

    Endpoint security schemeNon Secured (If secured, user is asked for credentials of the backend service)

  4. Click Manage to go to the Manage tab and provide the following information. 

    FieldValueDescription
    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.

    Tip

    Tip: For resources that have methods requiring authentication (i.e., Auth Type is not NONE), you set  None  as the Auth type of OPTIONS to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway.

  5. Once you are done, click Save. Before we publish the API, let's document its parameters.

Adding API documentation

  1. After creating saving the API, click on its icon thumbnail in the API Publisher to open its details. Select the Docs tab.

    Click Add New Document link. Image Removed

    Documentation can be provided

    it.

  2. Click on the API's Docs tab and note that you can create documentation 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:

    • How To
    • Samples and SDK
    • Public forum / Support forum (external link only)
    • API message formats
    • Other

  3. Click the Add New Document link. Image Added

  4. Select the How To type, a name for the document and a short description, which will appear in the API Store. Select inline or provide a URL.
  5. Click Add Document.

  6. Once the document is added, click Edit Content link, which opens an embedded editor to edit the document contents.

...

Adding interactive documentation

The API Manager provides facility to add interactive documentation support through the integration of Swagger. Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. In Swagger, when APIs are described in simple static JSON representation, they can be loaded through the Swagger UI, which in turn provides the interactive documentation.

When an API is created, the JSON representation of that API is automatically generated and saved into the registry as API definition. This definition describes the API with the information provided at the API creation level. You can customize the automatically generated API definition as follows:

  1. Click the Edit link right next to the API's name in the API Publisher to open it in the edit mode.
     
  2.  Click the Edit Swagger Definition button.

  3. When the Swagger definition of the API opens, document the parameters required by the API Console.
    For example, the PhoneVerification API requires a telephone number and a license key. You can document this by adding the following under the parameters section of the GET method:

    Code Block
    parameters:
   - description: Request Body
     name: body
     allowMultiple: false
     required: true
     type: string
     paramType: body
   - description: Give the phone number to be validated
     name: PhoneNumber
     type: string
     required: "True"
     paramType: query
   - description: "Give the license key. If you don't have any, enter 0"
     name: LicenseKey
     type: string
     required: "True"
     paramType: query


  4. Click Save once the changes are done.

...