Overview

Before we dig in, here is a high-level overview of Cosmic.

REST and RPC

The definition of REST is a controversial subject. For our purposes, these are the key elements:

• Objects are assigned unique URLs.
• These URLs are used to link objects together.
• Objects are manipulated by a set of standard methods (CRUD).

It is fairly straightforward to create a REST API from a database table, but other kinds of information can be expressed with REST as well. In general it is a good idea to try, and fall back on RPC only if REST is clearly a bad fit.

RPC stands for “remote procedure call”. It is a simple interface where a client sends a request to call a remote function with certain parameters and gets the return value of the function in the response. You might find many discussions online that are framed as “REST vs RPC”, but in reality they are tools that complement each other.

Architecture

Cosmic is a layer that sits between business code and HTTP. This is true for both the client and server components. In fact, if you were to draw the client and the server component, you’ll see that they are perfectly symmetrical.

Because of the above, and because API clients are to be built from a JSON spec generated by the server, we decided to implement the API class as a serializable type. When you serialize a server-side Cosmic API, you get the JSON spec, when you deserialize it on a different machine, you get an API client. The serialization is done by Teleport.

Cosmic abstracts HTTP into endpoints. An endpoint is a rule for serving a function via HTTP. It contains both the server and the client component. For the server, it defines parse_request() and build_response() methods. For the client, it defined build_request() and parse_response(). The reason the server and the client components are grouped in one object is that the client’s build_request() method is intimately related to the server’s parse_request() method. Similarly, build_response() and parse_response() are perfectly symmetrical.

Cosmic treats HTTP as an elaborate serialization scheme and takes full responsibility for it, leaving you with natively-behaving functions.

Built on Teleport

See also

The Teleport documentation is worth a look if you are getting started with Cosmic.

Teleport is our very own library that is used for JSON serialization, validation, and generating documentation. At first this might seem like an odd set of features for a library, but they come quite naturally from the fact that Teleport is essentially a very simple static type system. All information that gets carried between Cosmic clients and servers is statically typed with the help of Teleport.

Teleport is implemented as a collection of composable type objects. The composition of these objects mirrors the data it is meant to serialize and validate. One important feature of Teleport is that this composition, the schema, is also serializable. This makes it possible to use Teleport to serialize model properties and function definition, which are necessary to serialize the API.

Teleport makes it easy to define custom types, a feature used by Cosmic.

The Teleport docs will teach you to import from the teleport module:

from teleport import *

In Cosmic, you should import from cosmic.types:

from cosmic.types import *

Hypermedia with JSON HAL

JSON HAL is a compact specification for linking REST-ful resources as well as returning multiple embedded resources in one call (this is used by the get_list endpoint). Note that HAL recommends application/hal+json for the Content-Type header, but currently Cosmic responds only to application/json.