This class represents the common interface for the server-side and the client-side API objects. It contains the API spec as well as a collection of functions for each API endpoint. On the server side, these functions are user-defined. On the client side, they are created automatically to execute HTTP calls.
This stores the action functions as properties of a plain object:
>>> spelling.actions.correct('simpl')
"simple"
Through this property you can access the model functions get_by_id(), get_list(), create(), update() and delete(). They are accessed as attributes:
>>> quotes.models.Quote.get_by_id("1")
{"text": "Know thyself.", "author": "Socrates"}
Bases: cosmic.api.BaseAPI
Parameters: |
|
---|
Simple way to run the API in development. The debug parameter gets passed into a Server instance, all other parameters - into Werkzeug’s run_simple(). For more serving options, see Serving.
A decorator for registering actions with API.
The accepts parameter is a schema that describes the input of the function, returns is a schema that describes the output of the function. The name of the function becomes the name of the action and the docstring serves as the action’s documentation.
Once registered, an action will become accessible as an attribute of the actions object.
>>> random = API("random")
>>> @random.action(returns=Integer)
... def generate():
... "Random enough"
... return 9
>>> random.actions.generate()
9
A decorator for registering a model with an API. The name of the model class is used as the name of the resulting model. A subclass of BaseModel is used to supply the necessary metadata and functions to the API.
>>> dictionary = API("dictionary")
>>> @dictionary.model
... class Word(BaseModel):
... properties = [
... required("text", String)
... ]
...
Once registered, a model will become accessible as an attribute of the models object.
Subclasses of this class are fed into the model() decorator to attach models to an API. The API object doesn’t care about how you implement this class, it just copies the necessary properties and leaves the class alone.
A list of properties which, along with links below, will be used for the model’s representation and patch, defined in the same way Teleport Struct fields are defined:
properties = [
required('name', String),
optional('age', Integer),
]
See Representation and Patch.
Similar to properties, but encodes a relationship between this model and another. In database terms this would be a foreign key. Use required_link() and optional_link() to specify them.
A list of methods that this model supports. Possible values are 'get_by_id', 'create', 'update', 'delete' and 'get_list'.
A list of properties for the get_list() handler. They are defined in the same way as properties above.
A list of properties that can be returned along with the usual response for get_list(). These can be used for things like pagination.
Parameters: | id – |
---|---|
Returns: | Model representation |
Raises cosmic.exceptions.NotFound: | |
Parameters: | kwargs – Defined by query_fields |
---|---|
Returns: | If model does not define list_metadata, returns a list of tuples of models ids and representations. Otherwise returns a tuple where the first element is the above list, and the second is a dict as specified by list_metadata. |
Parameters: | validated_patch – The model patch. |
---|---|
Returns: | A tuple of model id and model representation. |
Parameters: |
|
---|---|
Returns: | The model representation after patch has been applied. |
Raises cosmic.exceptions.NotFound: | |
Parameters: | id – |
---|---|
Raises cosmic.exceptions.NotFound: | |
Parameters: | patch – The model patch |
---|---|
Raises cosmic.exceptions.ValidationError: | |
Run before any create() or update() call to validate the patch. All fields are made optional for the patch, so this method is a chance to ensure that the expected values were indeed passed in.
Bases: teleport.BasicWrapper
A Teleport type representing an API model. Its JSON form is a dotted string, the native form is an instance of this class.
Bases: teleport.ParametrizedWrapper
A Teleport type representing a link to an object. Its native form is simply a resource id. It takes a Model as parameter:
>>> Link(Model('places.City')).to_json("3")
{"href": "/City/3"}
>>> Link(Model('places.City')).from_json({"href": "/City/3"})
"3"
Bases: cosmic.types.BaseRepresentation
A Teleport type representing a model representation. Its native form is a dict as defined by properties and links. Links are represented by plain string ids.
It takes a Model as parameter.
Bases: cosmic.types.BaseRepresentation
A Teleport type representing a model patch. Its native form is similar to that of Representation, except all fields are optional. To make a field required, use validate_patch().
It takes a Model as parameter.
Bases: teleport.ParametrizedWrapper
A Teleport type that behaves mostly like the Struct type, except it serializes the data into a query string:
>>> p = URLParams([
... required("foo", Boolean),
... required("bar", Integer)
... ])
...
>>> p.to_json({"foo": True, "bar": 3})
'foo=true&bar=3'
>>> p.from_json("foo=false&bar=0")
{'foo': False, 'bar': 0}
A string parameter or a parameter whose type is a wrapper over string will not require quotes:
>>> from cosmic.types import DateTime
>>> schema = URLParams([
... required('birthday', DateTime)
... ])
>>> schema.from_json('birthday=1991-08-12T00%3A00%3A00')
{'birthday': datetime.datetime(1991, 8, 12, 0, 0)}
Bases: teleport.BasicWrapper
The teleport type that encapsulates all metadata associated with an API. This type is used to prepare the output for the /spec.json endpoint, as well as to deserialize it when building an API client.
What’s inside? Well, if you insist:
Struct([
required("name", String),
optional("homepage", String),
required("actions", OrderedMap(Struct([
optional("accepts", Schema),
optional("returns", Schema),
optional("doc", String)
]))),
required("models", OrderedMap(Struct([
required("properties", OrderedMap(Struct([
required("schema", Schema),
required("required", Boolean),
optional("doc", String)
]))),
required("links", OrderedMap(Struct([
required("model", Model),
required("required", Boolean),
optional("doc", String)
]))),
required("query_fields", OrderedMap(Struct([
required("schema", Schema),
required("required", Boolean),
optional("doc", String)
]))),
required("methods", Struct([
required("get_by_id", Boolean),
required("get_list", Boolean),
required("create", Boolean),
required("update", Boolean),
required("delete", Boolean),
])),
required("list_metadata", OrderedMap(Struct([
required("schema", Schema),
required("required", Boolean),
optional("doc", String)
])))
])))
])
Request: |
|
||||||||
---|---|---|---|---|---|---|---|---|---|
Response: |
|
Request: |
|
||||||
---|---|---|---|---|---|---|---|
Response: |
|
Request: |
|
||||||||
---|---|---|---|---|---|---|---|---|---|
Response: |
|
Request: |
|
||||||||
---|---|---|---|---|---|---|---|---|---|
Response: |
|
Request: |
|
||||
---|---|---|---|---|---|
Response: |
|
Request: |
|
||||||
---|---|---|---|---|---|---|---|
Response: |
|
Expected to be raised by get_by_id(), update() and delete() when the resource is not found. Cosmic will convert it to a 404 response on the server, and on the client, it will interpret this response by reraising the exception.
Given a function, returns a tuple (required, optional), tuples of non-keyword and keyword arguments respectively. If a function contains splats (* or **), a SpecError will be raised.
Takes arbitrary args and kwargs and packs them into a dict if there are more than one. Returns None if there are no arguments. Must be called with either a single argument or multiple keyword arguments.
Raises a SpecError if function argument spec (as returned by get_args()) is incompatible with the given schema. By incompatible, it is meant that there exists such a piece of data that is valid according to the schema, but that could not be applied to the function by apply_to_func().