Adapters¶
Adapters are responsible for transforming a Resource instance into a request body string. For example, in the SirenAdapter, they would put the properties in a dictionary called “properties”, the related resource in a list called “entities”, and so on and so forth. All adapters instantiation requires at least a resource instance.
Finally, adapters are independent of web framework and database/managers used. This means that you can completely reuse adapters across all of your applications.
Building your own adapter¶
At some point or another, you will probably want to roll out your own adapter. Maybe you are using a front-end framework that is expecting a specific format or maybe you’re porting over from django-rest-framework and don’t want to have to change your front-end. Either way, you want some flexibility in how the resource gets formatted.
For an example of a basic adapter check out the built in JSON adapter.
Required pieces¶
-
formats
¶ A tuple or list of available formats in unicode/str form. These are the formats that are used to match the requests accept-types with the appropriate adapter.
-
AdapterBase.
formatted_body
¶ This property is the fully qualified and formatted response. For example, you might return a Hypermedia formatted response body such as the SIREN hypermedia protocol or HAL. This must be overridden by any subclass. Additionally, it is a property and must be decorated as such.
Returns: The formatted response body. Return type: unicode
-
AdapterBase.
extra_headers
¶ Headers that should be added to response. For example it might be the content-type etc... This must be overridden by any subclass since it raises a NotImplementedError. It can also be overridden as a class attribute if it will not be dynamic.
Returns: A dictionary of the headers to return. Return type: dict
Optional pieces¶
These methods do not have to be implemented in the subclass but in some cases it may make more sense.
-
classmethod
AdapterBase.
format_exception
(exc)[source]¶ Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.
Parameters: exc (Exception) – The exception to format. Returns: A tuple containing: response body, format, http response code Return type: tuple
Adapters API¶
Built in adapters¶
-
class
ripozo.adapters.siren.
SirenAdapter
(resource, base_url=u'')[source]¶ An adapter that formats the response in the SIREN format. A description of a SIREN format can be found here: SIREN specification
-
classmethod
format_exception
(exc)[source]¶ Takes an exception and appropriately formats it in the siren format. Mostly. It doesn’t return a self in this circumstance.
Parameters: exc (Exception) – The exception to format. Returns: A tuple containing: response body, format, http response code Return type: tuple
-
classmethod
format_request
(request)[source]¶ Simply returns request
Parameters: request (RequestContainer) – The request to handler Return type: RequestContainer
-
formatted_body
¶ Gets the formatted body of the response in unicode form. If
self.status_code == 204
then this will return an empty string.Returns: The siren formatted response body Return type: unicode
-
generate_fields_for_endpoint_funct
(endpoint_func)[source]¶ Returns the action’s fields attribute in a SIREN appropriate format.
Parameters: endpoint_func (apimethod) – Returns: A dictionary of action fields Return type: dict
-
classmethod
-
class
ripozo.adapters.jsonapi.
JSONAPIAdapter
(resource, base_url=u'')[source]¶ An adapter for formatting and ResourceBase instance in an appropriate format. See the specification for more details on what format it will return.
-
classmethod
format_exception
(exc)[source]¶ Responsible for formatting the exception according to the error formatting specification
Parameters: exc (Exception) – The exception to format Returns: The response body, content type and status code as a tuple in that order. Return type: unicode, unicode, int
-
classmethod
format_request
(request)[source]¶ Unwraps a JSONAPI request according to the `specification .<http://jsonapi.org/format/#crud>`_ Basically, it reformats the attributes and relationships to be top level and dot formatted instead of an underlying dictionary.
Parameters: request (RequestContainer) – The request whose request body should be updated Returns: The updated request ready for ripozo. Return type: RequestContainer
-
formatted_body
¶ Returns a string in the JSON API format.
Returns: The appropriately formatted string Return type: unicode|str
-
classmethod
-
class
ripozo.adapters.hal.
HalAdapter
(resource, base_url=u'')[source]¶ An adapter that formats the response in the HAL format. A description of the HAL format can be found here: HAL Specification
-
classmethod
format_exception
(exc)[source]¶ Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.
Parameters: exc (Exception) – The exception to format. Returns: A tuple containing: response body, format, http response code Return type: tuple
-
classmethod
format_request
(request)[source]¶ Simply returns request
Parameters: request (RequestContainer) – The request to handler Return type: RequestContainer
-
generate_relationship
(relationship_list)[source]¶ Generates an appropriately formated embedded relationship in the HAL format.
Parameters: relationship (ripozo.viewsets.relationships.relationship.BaseRelationship) – The relationship that an embedded version is being created for. Returns: If it is a ListRelationship it will return a list/collection of the embedded resources. Otherwise it returns a dictionary as specified by the HAL specification. Return type: list|dict
-
classmethod
-
class
ripozo.adapters.basic_json.
BasicJSONAdapter
(resource, base_url=u'')[source]¶ Just a plain old JSON dump of the properties. Nothing exciting.
Format:
<resource_name>: { field1: "value" field2: "value" relationship: { relationship_field: "value" } list_relationship: [ { relationship_field: "value" } { relationship_field: "value" } ] }
-
classmethod
format_exception
(exc)[source]¶ Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.
Parameters: exc (Exception) – The exception to format. Returns: A tuple containing: response body, format, http response code Return type: tuple
-
classmethod
Base Adapter¶
-
class
ripozo.adapters.base.
AdapterBase
(resource, base_url=u'')[source]¶ The adapter base is responsible for specifying how a resource should be translated for the client. For example, you may want to specify a specific hypermedia protocol or format it in a manner that is specific to your client (though you should probably avoid that)
Parameters: formats (list) – A list of strings that indicate which Content-Types will match with this adapter. For example, you might include ‘application/vnd.siren+json’ in the formats for a SIREN adapter. This means that any request with that content type will be responded to in the appropriate manner. Any of the strings in the list will be considered the appropriate format for the adapter on which they are specified. -
combine_base_url_with_resource_url
(resource_url)[source]¶ Does exactly what it says it does. Uses
join_url_parts
with theself.base_url
andresource_url
argument together.Parameters: resource_url (unicode) – The part to join with the self.base_url
Returns: The joined url Return type: unicode
-
extra_headers
Headers that should be added to response. For example it might be the content-type etc... This must be overridden by any subclass since it raises a NotImplementedError. It can also be overridden as a class attribute if it will not be dynamic.
Returns: A dictionary of the headers to return. Return type: dict
-
classmethod
format_exception
(exc)[source] Takes an exception and appropriately formats the response. By default it just returns a json dump of the status code and the exception message. Any exception that does not have a status_code attribute will have a status_code of 500.
Parameters: exc (Exception) – The exception to format. Returns: A tuple containing: response body, format, http response code Return type: tuple
-
classmethod
format_request
(request)[source]¶ Takes a request and appropriately reformats the request. For example, jsonAPI requires a specific request format that must be transformed to work with ripozo. For this base implementation it simply returns the request without any additional formating.
Parameters: request (RequestContainer) – The request to reformat. Returns: The formatted request. Return type: RequestContainer
-
formatted_body
This property is the fully qualified and formatted response. For example, you might return a Hypermedia formatted response body such as the SIREN hypermedia protocol or HAL. This must be overridden by any subclass. Additionally, it is a property and must be decorated as such.
Returns: The formatted response body. Return type: unicode
-