Skip to content
Framework for creating self-describing APIs
Ruby Elixir JavaScript HTML PHP Makefile Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
clients
doc
examples/servers/ruby
servers
templates/ruby
utils
.editorconfig
.gitignore
CHANGELOG.md
Makefile
README.md
VERSION
shell.nix

README.md

HaveAPI

HaveAPI defines a protocol for self-describing RESTful APIs. This repository contains documentation of said protocol and a reference implementation of both server and client side libraries.

What is a self-describing API?

A self-describing API knows about itself what resources and actions it contains. It is able to send this information to clients in a machine-readable form. The API responds to HTTP method OPTIONS and returns the description of available resources, actions, their input/output parameters, labels, text notes, data types, validators and example usage.

Clients use the self-description to learn how to communicate with the API, which they otherwise know nothing about.

Motivation

Whenever you create an API server, you need to implement clients in various programming languages to work with it. Even if you make all APIs similar using e.g. REST or SOAP, you still need clients to know what resources and actions the API has, what are their parameters, and so on.

When your API speaks the HaveAPI protocol, you can use pre-created clients that will know how to work with it. You can do this by using this framework to handle all HaveAPI-protocol stuff for you, or you can implement the protocol on your own.

Available server frameworks:

Available clients:

Complex applications can be built on top of these basic clients, e.g.:

  • haveapi-webui, a generic web administration for HaveAPI-based APIs
  • haveapi-fs, a FUSE based filesystem that can mount any HaveAPI-based API

If there isn't a client in the language you need, you can create it and then use it for all HaveAPI-based APIs.

Protocol features

  • Creates RESTful APIs usable even with simple HTTP client, should it be needed
  • A change in the API is immediately reflected in all clients when they re-download the documentation
  • Generic interface for clients - one client can be used to access all APIs that implement this protocol
  • Supports API versioning
  • Standardised authentication methods
  • Defines action input/output parameters and their validators
  • Clients can monitor progress of long-running actions

Read more

You can’t perform that action at this time.