api-swagger.json

{
  "swagger" : "2.0",
  "info" : {
    "description" : "RESTful API of [Request Baskets](https://rbaskets.in) service.\n\nRequest Baskets is an open source project of a service to collect HTTP requests and inspect them via RESTful\nAPI or web UI.\n\nCheck out the [project page](https://github.com/darklynx/request-baskets) for more detailed description.\n",
    "version" : "0.8",
    "title" : "Request Baskets API",
    "contact" : {
      "name" : "darklynx",
      "url" : "https://github.com/darklynx"
    },
    "license" : {
      "name" : "MIT",
      "url" : "https://github.com/darklynx/request-baskets/blob/master/LICENSE"
    }
  },
  "host" : "rbaskets.in",
  "basePath" : "/",
  "tags" : [ {
    "name" : "baskets",
    "description" : "Manage baskets"
  }, {
    "name" : "responses",
    "description" : "Configure basket responses"
  }, {
    "name" : "requests",
    "description" : "Manage collected requests"
  } ],
  "schemes" : [ "https" ],
  "consumes" : [ "application/json" ],
  "produces" : [ "application/json" ],
  "paths" : {
    "/baskets" : {
      "get" : {
        "tags" : [ "baskets" ],
        "summary" : "Get baskets",
        "description" : "Fetches a list of basket names managed by service. Require master token.",
        "parameters" : [ {
          "name" : "max",
          "in" : "query",
          "description" : "Maximum number of basket names to return; default 20",
          "required" : false,
          "type" : "integer"
        }, {
          "name" : "skip",
          "in" : "query",
          "description" : "Number of basket names to skip; default 0",
          "required" : false,
          "type" : "integer"
        }, {
          "name" : "q",
          "in" : "query",
          "description" : "Query string to filter result, only those basket names that match the query will be included in response",
          "required" : false,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "OK. Returns list of available baskets.",
            "schema" : {
              "$ref" : "#/definitions/Baskets"
            }
          },
          "204" : {
            "description" : "No Content. No baskets available for specified limits"
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing master token"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      }
    },
    "/baskets/{name}" : {
      "get" : {
        "tags" : [ "baskets" ],
        "summary" : "Get basket settings",
        "description" : "Retrieves configuration settings of this basket.",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "OK. Returns basket configuration",
            "schema" : {
              "$ref" : "#/definitions/Config"
            }
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      },
      "post" : {
        "tags" : [ "baskets" ],
        "summary" : "Create new basket",
        "description" : "Creates a new basket with this name.",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The name of new basket",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "config",
          "description" : "Basket configuration",
          "required" : false,
          "schema" : {
            "$ref" : "#/definitions/Config"
          }
        } ],
        "responses" : {
          "201" : {
            "description" : "Created. Indicates that basket is successfully created",
            "schema" : {
              "$ref" : "#/definitions/Token"
            }
          },
          "400" : {
            "description" : "Bad Request. Failed to parse JSON into basket configuration object."
          },
          "403" : {
            "description" : "Forbidden. Indicates that basket name conflicts with reserved paths; e.g. `baskets`, `web`, etc."
          },
          "409" : {
            "description" : "Conflict. Indicates that basket with such name already exists"
          },
          "422" : {
            "description" : "Unprocessable Entity. Basket configuration is not valid."
          }
        }
      },
      "put" : {
        "tags" : [ "baskets" ],
        "summary" : "Update basket settings",
        "description" : "Updates configuration settings of this basket.\n\nSpecial configuration parameters for request forwarding:\n  * `insecure_tls` controls certificate verification when forwarding requests. Setting this parameter to `true`\n  allows to forward collected HTTP requests via HTTPS protocol even if the forward end-point is configured with\n  self-signed TLS/SSL certificate. **Warning:** enabling this feature has known security implications.\n  * `expand_path` changes the logic of constructing taget URL when forwarding requests. If this parameter is\n  set to `true` the forward URL path will be expanded when original HTTP request contains compound path. For\n  example, a basket with name **server1** is configured to forward all requests to `http://server1.intranet:8001/myservice`\n  and it has received an HTTP request like `GET http://baskets.example.com/server1/component/123/events?status=OK`\n  then depending on `expand_path` settings the request will be forwarded to:\n    * `true` => `GET http://server1.intranet:8001/myservice/component/123/events?status=OK`\n    * `false` => `GET http://server1.intranet:8001/myservice?status=OK`\n",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "config",
          "description" : "New configuration to apply",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Config"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content. Basket configuration is updated"
          },
          "400" : {
            "description" : "Bad Request. Failed to parse JSON into basket configuration object."
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          },
          "422" : {
            "description" : "Unprocessable Entity. Basket configuration is not valid."
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      },
      "delete" : {
        "tags" : [ "baskets" ],
        "summary" : "Delete basket",
        "description" : "Permanently deletes this basket and all collected requests.",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content. Basket is deleted"
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      }
    },
    "/baskets/{name}/responses/{method}" : {
      "get" : {
        "tags" : [ "responses" ],
        "summary" : "Get response settings",
        "description" : "Retrieves information about configured response of the basket. Service will reply with this response to any\nHTTP request sent to the basket with appropriate HTTP method.\n\nIf nothing is configured, the default response is HTTP 200 - OK with empty content.\n",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        }, {
          "name" : "method",
          "in" : "path",
          "description" : "The HTTP method this response is configured for",
          "required" : true,
          "type" : "string",
          "enum" : [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS", "TRACE" ]
        } ],
        "responses" : {
          "200" : {
            "description" : "OK. Returns configured response information",
            "schema" : {
              "$ref" : "#/definitions/Response"
            }
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      },
      "put" : {
        "tags" : [ "responses" ],
        "summary" : "Update response settings",
        "description" : "Allows to configure HTTP response of this basket. The service will reply with configured response to any HTTP\nrequest sent to the basket with appropriate HTTP method.\n\nIf nothing is configured, the default response is HTTP 200 - OK with empty content.\n",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        }, {
          "name" : "method",
          "in" : "path",
          "description" : "The HTTP method this response is configured for",
          "required" : true,
          "type" : "string",
          "enum" : [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS", "TRACE" ]
        }, {
          "in" : "body",
          "name" : "response",
          "description" : "HTTP response configuration",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Response"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content. Response configuration is updated"
          },
          "400" : {
            "description" : "Bad Request. Failed to parse JSON into response configuration object."
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          },
          "422" : {
            "description" : "Unprocessable Entity. Response configuration is not valid."
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      }
    },
    "/baskets/{name}/requests" : {
      "get" : {
        "tags" : [ "requests" ],
        "summary" : "Get collected requests",
        "description" : "Fetches collection of requests collected by this basket.",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        }, {
          "name" : "max",
          "in" : "query",
          "description" : "Maximum number of requests to return; default 20",
          "required" : false,
          "type" : "integer"
        }, {
          "name" : "skip",
          "in" : "query",
          "description" : "Number of requests to skip; default 0",
          "required" : false,
          "type" : "integer"
        }, {
          "name" : "q",
          "in" : "query",
          "description" : "Query string to filter result, only requests that match the query will be included in response",
          "required" : false,
          "type" : "string"
        }, {
          "name" : "in",
          "in" : "query",
          "description" : "Defines what is taken into account when filtering is applied: `body` - search in content body of collected requests,\n`query` - search among query parameters of collected requests, `headers` - search among request header values,\n`any` - search anywhere; default `any`\n",
          "required" : false,
          "type" : "string",
          "enum" : [ "any", "body", "query", "headers" ]
        } ],
        "responses" : {
          "200" : {
            "description" : "OK. Returns list of basket requests.",
            "schema" : {
              "$ref" : "#/definitions/Requests"
            }
          },
          "204" : {
            "description" : "No Content. No requests found for specified limits"
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      },
      "delete" : {
        "tags" : [ "requests" ],
        "summary" : "Delete all requests",
        "description" : "Deletes all requests collected by this basket.",
        "parameters" : [ {
          "name" : "name",
          "in" : "path",
          "description" : "The basket name",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content. Basket requests are cleared"
          },
          "401" : {
            "description" : "Unauthorized. Invalid or missing basket token"
          },
          "404" : {
            "description" : "Not Found. No basket with such name"
          }
        },
        "security" : [ {
          "basket_token" : [ ]
        } ]
      }
    }
  },
  "securityDefinitions" : {
    "basket_token" : {
      "description" : "Basket assigned secure token",
      "type" : "apiKey",
      "name" : "Authorization",
      "in" : "header"
    }
  },
  "definitions" : {
    "Baskets" : {
      "type" : "object",
      "required" : [ "has_more", "names" ],
      "properties" : {
        "names" : {
          "type" : "array",
          "description" : "Collection of basket names",
          "items" : {
            "type" : "string"
          }
        },
        "count" : {
          "type" : "integer",
          "description" : "Total number of baskets in the system; not present if query is applied"
        },
        "has_more" : {
          "type" : "boolean",
          "description" : "Indicates if there are more baskets to fetch"
        }
      }
    },
    "Config" : {
      "type" : "object",
      "properties" : {
        "forward_url" : {
          "type" : "string",
          "description" : "URL to forward all incoming requests of the basket, `empty` value disables forwarding"
        },
        "proxy_response" : {
          "type" : "boolean",
          "description" : "If set to `true` this basket behaves as a full proxy: responses from underlying service configured in `forward_url`\nare passed back to clients of original requests. The configuration of basket responses is ignored in this case.\n"
        },
        "insecure_tls" : {
          "type" : "boolean",
          "description" : "If set to `true` the certificate verification will be disabled if forward URL indicates HTTPS scheme.\n**Warning:** enabling this feature has known security implications.\n"
        },
        "expand_path" : {
          "type" : "boolean",
          "description" : "If set to `true` the forward URL path will be expanded when original HTTP request contains compound path."
        },
        "capacity" : {
          "type" : "integer",
          "description" : "Baskets capacity, defines maximum number of requests to store"
        }
      }
    },
    "Token" : {
      "type" : "object",
      "required" : [ "token" ],
      "properties" : {
        "token" : {
          "type" : "string",
          "description" : "Secure token to manage the basket, generated by system"
        }
      }
    },
    "Requests" : {
      "type" : "object",
      "required" : [ "has_more", "requests" ],
      "properties" : {
        "requests" : {
          "type" : "array",
          "description" : "Collection of collected requests",
          "items" : {
            "$ref" : "#/definitions/Request"
          }
        },
        "count" : {
          "type" : "integer",
          "description" : "Current number of collected requests hold by basket; not present if query is applied"
        },
        "total_count" : {
          "type" : "integer",
          "description" : "Total number of all requests passed through this basket; not present if query is applied"
        },
        "has_more" : {
          "type" : "boolean",
          "description" : "Indicates if there are more requests collected by basket to fetch"
        }
      }
    },
    "Request" : {
      "type" : "object",
      "properties" : {
        "date" : {
          "type" : "integer",
          "format" : "int64",
          "description" : "Date and time of request in Unix time ms. format (number of miliseconds elapsed since January 1, 1970 UTC)"
        },
        "headers" : {
          "$ref" : "#/definitions/Headers"
        },
        "content_length" : {
          "type" : "integer",
          "description" : "Content lenght of request"
        },
        "body" : {
          "type" : "string",
          "description" : "Content of request body"
        },
        "method" : {
          "type" : "string",
          "description" : "HTTP methof of request"
        },
        "path" : {
          "type" : "string",
          "description" : "URL path of request"
        },
        "query" : {
          "type" : "string",
          "description" : "Query parameters of request"
        }
      }
    },
    "Headers" : {
      "type" : "object",
      "description" : "Map of HTTP headers, key represents name, value is array of values",
      "additionalProperties" : {
        "type" : "array",
        "description" : "Collection of header values",
        "items" : {
          "type" : "string"
        }
      }
    },
    "Response" : {
      "type" : "object",
      "properties" : {
        "status" : {
          "type" : "integer",
          "description" : "The HTTP status code to reply with"
        },
        "headers" : {
          "$ref" : "#/definitions/Headers"
        },
        "body" : {
          "type" : "string",
          "description" : "Content of response body"
        },
        "is_template" : {
          "type" : "boolean",
          "description" : "If set to `true` the body is treated as [HTML template](https://golang.org/pkg/html/template) that accepts\ninput from request parameters.\n"
        }
      }
    }
  }
}