Documentation

What does Protean do ?

Protean is a Clojure project which supports the design and evolution of RESTful APIs. It lets you:

• Specify an API
• Generate API documentation from the specification
• Run a simulation of an API - derived from the specification
• Run an integration test on an API - derived from the specification
• Hotswap API simulation behaviour on the fly over the network
• Autogenerate curl commands to interact with your API

How does Protean work ?

Protean includes a Server and a Client.

Building an API specification

Protean uses EDN to build an API specification. We call the specification a Codex. A Codex is an EDN file with a .cod.edn extension.

Protean ships with a sample Pet Store Codex and several more full featured examples and tutorials.

Generating API documentation

As soon as we have a Codex we can generate API documentation. The Protean Client uses Silk Web Toolkit to build the documentation for your API.

We can customise the API documentation by making changes to a directory called silk_templates which is in the same location as the Codex.

Running a simulation of your API

Once we have a Codex we can run an out of the box simulation derived from it using the Protean Server. Drop the Codex into place and start the server up.

We can customise the simulation by creating a Sim Extension. Place the Sim Extension in the same location as the Codex. Protean provides a comprehensive API and the full power of Clojure to let you customise your API simulation any way you want. A Sim Extension is an EDN file with a .sim.edn extension.

A list of commands

Server

• protean-server - start the Protean Server

Client

• protean doc -f /path/to/a-codex.cod.edn - generate API documentation
• protean services - list all the APIs (services)
• protean service -n an-api - show API (service) configuration
• protean service-usage -n an-api - show curl commands for interacting with the API