bravado
validates the schema against the Swagger 2.0 Spec. Validations are also done on the requests and the responses.
Validation example:
pet = Pet(id="I should be integer :(", name="tommy")
client.pet.addPet(body=pet).response().result
will result in an error like so:
TypeError: id's value: 'I should be integer :(' should be in types (<type 'long'>, <type 'int'>)
Note
If you'd like to disable validation of outgoing requests, you can set validate_requests
to False
in the config
passed to SwaggerClient.from_url(...)
.
The same holds true for incoming responses with the validate_responses
config option.
bravado
allows you to pass request headers along with any request.
Pet = client.get_model('Pet')
Category = client.get_model('Category')
pet = Pet(id=42, name="tommy", category=Category(id=24))
swagger_client.pet.addPet(
body=pet,
_request_options={"headers": {"foo": "bar"}},
).response().result
bravado
provides docstrings to operations and models to quickly get the parameter and response types. Due to an implementation limitation, an operation's docstring looks like a class docstring instead of a function docstring. However, the most useful information about parameters and return type is present in the Docstring
section.
Note
The help
built-in does not work as expected for docstrings. Use the ?
method instead.
>> petstore.pet.getPetById?
Type: CallableOperation
String Form:<bravado.client.CallableOperation object at 0x241b5d0>
File: /some/dir/bravado/bravado/client.py
Definition: c.pet.getPetById(self, **op_kwargs)
Docstring:
[GET] Find pet by ID
Returns a single pet
:param petId: ID of pet to return
:type petId: integer
:returns: 200: successful operation
:rtype: object
:returns: 400: Invalid ID supplied
:returns: 404: Pet not found
Constructor Docstring::type operation: :class:`bravado_core.operation.Operation`
Call def: c.pet.getPetById(self, **op_kwargs)
Call docstring:
Invoke the actual HTTP request and return a future that encapsulates
the HTTP response.
:rtype: :class:`bravado.http_future.HTTPFuture`
Docstrings for models can be retrieved as expected:
>> pet_model = petstore.get_model('Pet')
>> pet_model?
Type: type
String Form:<class 'bravado_core.model.Pet'>
File: /some/dir/bravado_core/model.py
Docstring:
Attributes:
category: Category
id: integer
name: string
photoUrls: list of string
status: string - pet status in the store
tags: list of Tag
Constructor information:
Definition:pet_type(self, **kwargs)
bravado
uses the default values from the spec if the value is not provided in the request.
In the Pet Store example, operation findPetsByStatus
has a default
of available
. That means, bravado
will plug that value in if no value is provided for the parameter.
client.pet.findPetByStatus()
bravado
also accepts swagger.json
from a file path. Like so:
client = SwaggerClient.from_url('file:///some/path/swagger.json')
Alternatively, you can also use the load_file
helper method.
from bravado.swagger_model import load_file
client = SwaggerClient.from_spec(load_file('/path/to/swagger.json'))
The default behavior for a service call is to return the swagger result like so:
pet = petstore.pet.getPetById(petId=42).response().result
print pet.name
However, there are times when it is necessary to have access to the actual HTTP response so that the HTTP headers or HTTP status code can be used. Simply save the response object (which is a .BravadoResponse
) and use its incoming_response
attribute to access the incoming response:
petstore = Swagger.from_url(
'http://petstore.swagger.io/swagger.json',
config={'also_return_response': True},
)
pet_response = petstore.pet.getPetById(petId=42).response()
http_response = pet_response.incoming_response
assert isinstance(http_response, bravado_core.response.IncomingResponse)
print http_response.headers
print http_response.status_code
print pet.name
By default, if the server returns an error or doesn't respond in time, you have to catch and handle the resulting exception accordingly. A simpler way would be to use the support for fallback results provided by .HttpFuture.response
.
.HttpFuture.response
takes an optional argument fallback_result
which is a callable that returns a Swagger result. The callable takes one mandatory argument: the exception that would have been raised normally. This allows you to return different results based on the type of error (e.g. a .BravadoTimeoutError
) or, if a server response was received, on any data pertaining to that response, like the HTTP status code.
In the simplest case, you can just specify what you're going to return:
petstore = Swagger.from_url('http://petstore.swagger.io/swagger.json')
response = petstore.pet.findPetsByStatus(status=['available']).response(
timeout=0.5,
fallback_result=lambda e: [],
)
This code will return an empty list in case the server doesn't respond quickly enough (or it responded quickly enough, but returned an error).
By default, the fallback result will be used either when the server doesn't send the response in time or when it returns a server error (i.e. a result with a HTTP 5XX status code). To override this behavior, specify the exceptions_to_catch
argument to .HttpFuture.response
.
The default is defined in bravado.http_future.FALLBACK_EXCEPTIONS
. See bravado.exception
for a list of possible exception types.
But what if you're using models (the default) and the endpoint you're calling returns one? You'll have to return one as well from your fallback_result function to stay compatible with the rest of your code:
petstore = Swagger.from_url('http://petstore.swagger.io/swagger.json')
response = petstore.pet.getPetById(petId=101).response(
timeout=0.5,
fallback_result=lambda e: petstore.get_model('Pet')(name='No Pet found', photoUrls=[]),
)
Two things to note here: first, use .SwaggerClient.get_model
to get the model class for a model name. Second, since name
and photoUrls
are required fields for this model, we probably should not leave them empty (if we do they'd still be accessible, but the value would be None
). It's up to you how you decide to deal with this case.
.BravadoResponseMetadata.is_fallback_result
will be True if a fallback result has been returned by the call to .HttpFuture.response
.
You can trigger returning fallback results for testing purposes. Just set the option force_fallback_result
to True
in the request configuration (see request_config
). In this case a .ForcedFallbackResultError
exception will be passed to your fallback result callback, so make sure you handle it properly.
Sometimes, there's additional metadata in the response that you'd like to make available easily. This case arises most often if you're using bravado to talk to internal services. Maybe you have special HTTP headers that indicate whether a circuit breaker was triggered? bravado allows you to customize the metadata and provide custom attributes and methods.
In your code, create a class that subclasses bravado.response.BravadoResponseMetadata
. In the implementation of your properties, use .BravadoResponseMetadata.headers
to access response headers, or .BravadoResponseMetadata.incoming_response
to access any other part of the HTTP response.
If, for some reason, you need your own __init__
method, make sure that your signature accepts any positional and keyword argument, and that you call the base method with these arguments from your own implementation. That way, your class will remain compatible with the base class even if new arguments get added to the __init__ method. Example minimal implementation:
class MyResponseMetadata(ResponseMetadata):
def __init__(self, *args, **kwargs):
super(MyResponseMetadata, self).__init__(*args, **kwargs)
While developing custom .BravadoResponseMetadata
classes we recommend to avoid, if possible, the usage of attributes for data that's expensive to compute. Since the object will be created for every response, implementing these fields as properties makes sure the evaluation is only done if the field is accessed.