Making requests with bravado

When you call SwaggerClient.from_url() or SwaggerClient.from_spec(), Bravado takes a Swagger (OpenAPI) 2.0 spec and returns a SwaggerClient instance that you can use to make calls to the service described in the spec. You make calls by doing Python method calls in the form of client.resource.operation(operation_params). Use dir(client) to see all available resources.

Resources and operations

Resources are generated for each tag that exists in your Swagger spec. If an operation has no tags then the left-most element of its path is taken as resource name. So in the case of an operation with the path /pet/find, pet will be the resource.

The operation name will be the (sanitized) operationId value from the Swagger spec. If there is no operationId, it will be generated. We highly recommend providing operation IDs for all operations. Use dir(client.resource) to see a list of all available operations.

The operation method expects keyword arguments that have the same (sanitized) names as in the Swagger spec. Use corresponding Python types for the values - if the Swagger spec says a parameter is of type boolean, provide it as a Python bool.

Futures and responses

The return value of the operation method is a HttpFuture. To access the response, call HttpFuture.response(). This call will block, i.e. it will wait until the response is received or the timeout you specified is reached.

If the request succeeded and the server returned a HTTP status code between 100 and 299, the return value of HttpFuture.response() will be a BravadoResponse instance. You may access the Swagger result of your call through BravadoResponse.result.

If the server sent a response with a HTTP code of 300 or higher, by default a subclass of HTTPError will be raised when you call HttpFuture.response(). The exception gives you access to the Swagger result (HTTPError.swagger_result) as well as the HTTP response object (HTTPError.response).

Response metadata

BravadoResponse.metadata is an instance of BravadoResponseMetadata that provides you with access to the HTTP response including headers and HTTP status code, request timings and whether a fallback result was used (see Working with fallback results).

You’re able to provide your own implementation of BravadoResponseMetadata; see Custom response metadata for details.

Sanitizing names

Not all characters that the Swagger spec allows for names are valid Python identifiers. In particular, spaces and the - character can be troublesome. bravado sanitizes resource, operation and parameter names according to these rules:

  • Any character that is not a letter or number is converted to an underscore (_)
  • Collapse multiple consecutive underscores to one
  • Remove leading and trailing underscores
  • Remove leading numbers