swagger: '2.0'

info:
  version: "0.9.0"
  title: "WSO2 API Manager"
  description: |
    This document describe a ** RESTFul API ** for wso2 **API Manager**.
    
    You can find the source of this API definition at [here](https://github.com/hevayo/restful-apim). It was written with [swagger 2](http://swagger.io/).

  contact:
    name: "WSo2"
    url: "http://wso2.com/products/api-manager/"
    email: "architecture@wso2.com"
  license: 
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
consumes: [ "application/json" ]
produces: [ "application/json" ]
schemes: [ "https" ]

paths:
  /apis:
    get:
      description: Get a list of available APIs qualifying under a given search condition.
      parameters:
        - 
          $ref : "#/parameters/limit"
        - 
          $ref : "#/parameters/offset"
        - 
          name : query
          in: query
          description: Search condition. 
          type: "string"
        -
          $ref : "#/parameters/Accept"
        -
          $ref : "#/parameters/If-None-Match"
      responses:
        200:
          description: OK. List of APIs is returned.
          schema:
            title: APIList
            type: object
            properties:
              count:
                type: string
              list:
                type: array
                items: 
                  $ref : "#/definitions/API"
          headers:
            Content-Type:
              description: The content type of the body.
              type: string
            ETag:
              description: Entity Tag of the response resource. Used by caches, or in conditional requests.
              type: string
        304:
          description: Not Modified. Empty body because the client has already the latest version of the requested resource.
        406:
          description: Not Acceptable. The requested media type is not supported
          schema:
            $ref: "#/definitions/Error"
    post:
      description: "Create a new API"
      parameters:
        - in: body
          name: body
          description: "API object that needs to be added"
          required: true
          schema:
            $ref: "#/definitions/API"
        -
          $ref : "#/parameters/Content-Type"
      responses:
        201:
          description: "Created. Successful response with the newly created API object as entity in the body. Location header contains URL of newly created entity."
          schema:
            $ref: "#/definitions/API"
          headers:
            Location:
              description: The URL of the newly created resource.
              type: string
            Content-Type:
              description: The content type of the body.
              type: string
            ETag:
              description: Entity Tag of the response resource. Used by caches, or in conditional request
              type: string
        400:
          description: "Bad Request. Invalid request or validation error."
          schema: 
            $ref: "#/definitions/Error"
        415:
          description: "Unsupported Media Type. The entity of the request was in a not supported format."
          schema:
            $ref: "#/definitions/Error"
            
  /apis/{apiId}:
    parameters:
      -  
        $ref: "#/parameters/apiId"
    get:
      description: Get details of an API
      parameters:
        -
          $ref : "#/parameters/Accept"
        -
          $ref : "#/parameters/If-None-Match"
        -
          $ref : "#/parameters/If-Modified-Since"
      responses:
        200:
          description: Successful response
          headers:
            Content-Type:
              description: The content type of the body.
              type: string
            ETag:
              description: Entity Tag of the response resource. Used by caches, or in conditional requests.
              type: string
            Last-Modified:
              description: Date and time the resource has been modifed the last time. Used by caches, or in conditional reuquests.
              type: string
          schema: 
            $ref : "#/definitions/API"
        304:
          description: Not Modified. Empty body because the client has already the latest version of the requested resource.
        404:
          description: Not Found. Requested API does not exist.
          schema: 
            $ref: "#/definitions/Error"     
        406:
          description: Not Acceptable. The requested media type is not supported
          schema:
            $ref: "#/definitions/Error"
    put:
      description: Update an existing API
      parameters:
        - in: body
          name: body
          description: "API object that needs to be added"
          required: true
          schema:
            $ref: "#/definitions/API"
        -
          $ref : "#/parameters/Content-Type"
        -
          $ref : "#/parameters/If-Match"
        -
          $ref : "#/parameters/If-Unmodified-Since"
      responses:
        200:
          description: OK. Successful response with updated API object
          schema:
            $ref: "#/definitions/API"  
          headers:
            Location:
              description: The URL of the newly created resource.
              type: string
            Content-Type:
              description: The content type of the body.
              type: string
            ETag:
              description: Entity Tag of the response resource. Used by caches, or in conditional request
              type: string
            Last-Modified:
              description: Date and time the resource has been modifed the last time. Used by caches, or in conditional reuquests.
              type: string
        400:
          description: Bad Request. Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Not Found. The resource to be updated does not exist.
          schema: 
            $ref: "#/definitions/Error"      
        412:
          description: Precondition Failed. The request has not been performed because one of the preconditions is not met.
          schema: 
            $ref: "#/definitions/Error"  
    delete:
      description: Delete an existing API
      parameters:
        -
          $ref : "#/parameters/If-Match"
        -
          $ref : "#/parameters/If-Unmodified-Since"
      responses:
        200:
          description: OK. Resource successfully deleted.
        404:
          description: Not Found. Resource to be deleted does not exist.
          schema: 
            $ref: "#/definitions/Error"   
        412:
          description: Precondition Failed. The request has not been performed because one of the preconditions is not met.
          schema: 
            $ref: "#/definitions/Error"
  /apis/{apiId}/copy-api:
    parameters:
      -
        $ref: "#/parameters/apiId"
    post:
      parameters:
        - name: newVersion
          description: Version of the new API.
          type: string
          in: formData
      description: Create a new API by coping and existing 
      responses:
        201:
          description: Successful response
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Requested API does not exist.
          schema: 
            $ref: "#/definitions/Error"          
  /apis/{apiId}/change-lifecycle:
    parameters:
      -
        $ref: "#/parameters/apiId"  
    post:
      description: Change the lifecycle of an API 
      responses:
        201:
          description: Successful response  
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Requested API does not exist.
          schema: 
            $ref: "#/definitions/Error"          
  /apis/{apiId}/documents:
    get:
      description: Get a list of documents belonging to an API 
      parameters:
        - 
          $ref : "#/parameters/limit"
        - 
          $ref : "#/parameters/offset"
        - 
          name : query
          in: query
          description: Search condition.  
          type: "string"
      responses:
        200:
          description: Successful response
          schema:
            title: DocumentList
            type: object
            properties:
              count:
                type: string
              list:
                type: array
                items: 
                  $ref : "#/definitions/Document"
        404:
          description: Requested API does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    post:
      description: Add a new document to an API 
      responses:
        201:
          description: Successful response
          headers:
            Link: 
              description: "Location to the newly created Document."
              type: "string"          
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"          
        404:
          description: Requested API does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    parameters:
      -
        $ref: "#/parameters/apiId"
  /apis/{apiId}/documents/{documentId}:
    get:
      description: Get the document details of an API 
      responses:
        200:
          description: Successful response
          schema:
            $ref : "#/definitions/Document"
        404:
          description: Requested API or Document does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    put:
      description: Update document details 
      responses:
        200:
          description: Successful response
          schema:
            $ref : "#/definitions/Document"          
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Requested API or Document does not exist. 
          schema: 
            $ref: "#/definitions/Error"          
    delete:
      description: Delete a document of an API
      responses:
        204:
          description: Successful response  
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"       
        404:
          description: Requested API or Document does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    parameters:
      -
        $ref: "#/parameters/apiId"
      -
        name: documentId
        in: path
        description: Document Id
        required: true
        type: number
        format: integer
  /applications:
    get:
      description: Get a list of Applications created
      parameters:
        - 
          $ref : "#/parameters/limit"
        - 
          $ref : "#/parameters/offset"       
      responses:
        200:
          description: Successful response
          schema:
            title: ApplicationList
            type: object
            properties:
              count:
                type: string
              list:
                type: array
                items: 
                  $ref : "#/definitions/Application"
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"              
    post:
      description: Create a new Application
      parameters:
        - in: body
          name: body
          description: "Application object that needs to be added"
          required: true
          schema:
            $ref: "#/definitions/Application"      
      responses:
        201:
          description: Successful response
          headers:
            Link: 
              description: "Location to the newly created Application."
              type: "string"          
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"          
        415:
          description: "Unsupported media type"
          schema:
            $ref: "#/definitions/Error"  
  /applications/{applicationId}:
    get:
      description: Get Application details
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/Application"
        404:
          description: Requested Application does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    put:
      description: Update application details
      responses:
        200:
          description: Successful response
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"  
        404:
          description: Requested Application does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    delete:
      description: Remove and application
      responses:
        204:
          description: Application was deleted successfully.
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Requested Application does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    parameters: 
      - $ref : "#/parameters/applicationId"
  /subscriptions:
    get:
      description: Get subscription list
      responses:
        200:
          description: Successful response        
    post:
      description: Add a new subscription
      responses:
        201:
          description: Successful response
          headers:
            Link: 
              description: "Location to the newly created Subscription."
              type: "string"
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"          
  /subscriptions/{subscriptionId}:
    get:
      description: Get subscription details
      responses:
        200:
          description: Successful response
          schema:
            $ref : "#/definitions/Subscription"
        404:
          description: Requested Subscription does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    put:
      description: Update subscription details
      responses:
        200:
          description: Successful response
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error" 
        404:
          description: Requested Subscription does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    delete:
      description: Remove subscription
      responses:
        204:
          description: Unsubscribe from an API
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"   
        404:
          description: Requested Subscription does not exist.
          schema: 
            $ref: "#/definitions/Error"          
    parameters: 
      -
        $ref : "#/parameters/subscriptionId" 
  /subscriptions/{subscriptionId}/block-subscription:
    put:
      parameters: 
        -
          $ref : "#/parameters/subscriptionId"
      description: Block a subscription.
      responses:
        200:
          description: Subscription was blocked successfully.
        400:
          description: Invalid request or validation error
          schema: 
            $ref: "#/definitions/Error"
        404:
          description: Requested Subscription does not exist.
          schema: 
            $ref: "#/definitions/Error"          
  /tiers:
    get:
      description: Get Available Tiers
      responses:
        200:
          description: Successful response
          schema:
            type: "array"
            items: 
              $ref : "#/definitions/Tier"
    
parameters:
  apiId:
    name: apiId
    in: path
    description: |
     **API ID** consisting name version and provider of the API. 
     Should be formated as **name/version/provider**
    required: true
    type: string
  applicationId:
    name: applicationId
    in: path
    description: "Application Id"
    required: true
    type: number
    format: integer
  subscriptionId:
    name: subscriptionId
    in: path
    description: "Subscription Id"
    required: true
    type: number
    format: integer
  limit:
    name: limit
    in: query
    description: Maximum size of API array to return.
    default: 25
    required: true
    type: number
    format: double
  offset:
    name: offset
    in: query
    description: Starting point of the item list.  
    default: 0
    required: true
    type: number
    format: double
  Accept:
    name : Accept
    in : header
    description: Media types for the response. Should denote XML or JSON, default is JSON.
    type : "string"
  Content-Type:
    name : Content-Type
    in : header
    description: Media type of the entity in the request body. Should denote XML or JSON, default is JSON.
    type : "string"
  If-None-Match:
    name : If-None-Match
    in : header
    description: Validator for conditional requests; based on ETag.
    type : "string"
  If-Modified-Since:
    name : If-Modified-Since
    in : header
    description: Validator for conditional requests; based on Last Modified header.
    type : "string"
  If-Match:
    name : If-Match
    in : header
    description: Validator for conditional requests; based on ETag.
    type : "string"
  If-Unmodified-Since:
    name : If-Unmodified-Since
    in : header
    description: Validator for conditional requests; based on Last Modified header.
    type : "string"

definitions:
  API:
    title: "API object"
    required: [ "name" , "context", "version" ]
    properties:
      name:
        type: "string"
      context:
        type: "string"
      version:
        type: "string"
      provider:
        type: "string"
      swagger:
        type: "string"
      status:
        type: "string"
      responseCaching:
        type: "string"
      isDefaultVersion:
        type: "boolean"
      transport:
        type: "array"
        items:
          type: "string"
          enum: [ "http", "https" ]
      tier:
        type: "string"
      visibility:
        type: "string"
        enum: ["public","private"]
      endpoint:
        type: "object"
        properties:
          type:
            type: "string"
            enum: ["http","address","wsdl","failover","load_balanced"]
          production:
            type: "array"
            items:
              type: "string"
          sandbox:
            type: "array"
            items:
              type: "string"
  # Following is the Application model, note the consumer key and secret
  Application:
    title: "Application"
    required: [ "applicationId" ]
    properties:
      applicationId:
        type: "string"
      name:
        type: "string"
      throttlingTier:
        type: "string"
      callbackUrl:
        type: "string"
      description:
        type: "string"
      consumerKey:
        type: "string"
      consumerSecret:
        type: "string"
      accessToken:
        type: "string"
  Document:
    title: "Document"
    required: ["documentId"]
    properties:
      documentId:
        type: "integer"
      name:
        trype: "string"
      type:
        trype: "string"
      summary:
        trype: "string"      
      content:
        trype: "string"      
      url:
        trype: "string"   
  Tier:
    title: "Tier"
    required: [ "name" ]
    properties:
      name:
        type: "string"
      rate:
        type: "string"
      roles:
        type: "string"
  
  Subscription:
    title: "Subscription"
    required: [ "subscriptionId" ]
    properties:
      subscriptionId:
        type: "number"
      applicationId:
        type: "string"
      apiId:
        type: "string"
      tier:
        type: "string"
      status:
        type: "string"
        
  Error:
    title: "Error object returned with 4XX HTTP status"
    required: [ "code", "message" ]
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string
        description: "Error message."
      description:
        type: string
        description: "A detail description about the error message."
      moreInfo:
        type: string
        description: "Preferably an url with more details about the error."
      error:
        type: array
        description: "If there are more than one error list them out. Ex. list out validation errors by each field." 
        items:
          $ref : "#/definitions/ErrorListItem"
  ErrorListItem:
    title: Description of individual errors that may have occored during a request.
    required: [ "code" , "message"]
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string
        description: "Description about individual errors occored"
        
        
