Transform your development workflow with hypermea, the toolkit that lets you rapidly create production-ready hypermedia-driven APIs. Equipped with advanced features, sophisticated error handling, expressive logging and much more, hypermea ensures your APIs are built to last, whether for small projects or enterprise-scale solutions. Discover the power of hypermedia APIs and how hypermea makes it easy.
Please note: We have been using hypermea internally for years to create real-life production microservice clusters. We are in the process of shrink-wrapping the package and polishing the documentation. This doc is under a heavy rewrite. Information here is mostly correct, but there are gaps and it's messy. Version 1.0.0 is coming soon. Until its release, proceed with caution.
Hypermedia is a simple idea with powerful results. If you are new to hypermedia, start here.
Please see the (work in progress) hypermea documentation.
With simple commands you generate a fully functional, hypermedia-driven API code base in minutes. No tedious setup.
Before opening your IDE you can add resources, links, affordances. Configure authentication, Git, Docker, and more.
Start with a solid foundation and focus on what matters: your business logic.
Out of the box your APIs are feature rich, including sorting, pagination, filtering, validation, bulk inserts, and much more.
The APIs you create leverage Flask, are powered by MongoDB, and are enriched by Eve. You get the benefits of those libraries without needing to learn them first.
With the hypermea-core library your API is hypermedia-based using HAL to represent your resources.
Eve is amazing. The full power of Flask/Python, optimized for an API over mongodb. Nice.
It does take a bit of work to go from the simple example in the docs...
settings = {'DOMAIN': {'people': {}}}
app = Eve(settings=settings)
app.run()...to a production-ready API, with robust exception handling, logging, control endpoints, configurability, (and so much more).
hypermea helps make some of that work easier.
Use the hypermea toolkit to create and craft your API. These are command line tools, similar to how you use git or docker.
All commands begin with hypermea and are followed by one of the following top-level commands:
| Command | Definition |
|---|---|
api |
This, unsurprisingly, represents the API service itself. When you run hypermea api create... a ton of code is generated, comprising your service. The code wraps start/stop (and other details) in a class called HypermeaService and your app is an instance of this class. HypermeaService inherits from Flask so your application is a Flask application as much as it is an hypermea/Eve application. |
resource |
These are the 'nouns' of your service. The set of resources you add to your API comprise the service domain. Use the HTTP verbs (GET, POST, DELETE, PATCH, etc.) to operate these resources, and add affordances to enhance state management beyond CRUD. |
link |
This creates a parent/child relationship between two resources and adds navigation affordances. |
affordance |
In a Hypermedia API, clients operate your service's state by way of hyperlinks. When you want to offer your clients the opportunity to do so, you provide a link which when requested with an HTTP verb causes the state change. See the Hypermedia section below for more details and examples. |
endpoint |
In the very unlikely event that you need to provide a capability that does not fit within the constraints of Hypermedia, you can define an arbitrary endpoint. Use that cautiously, lest the ghost of Roy Fielding haunt you :-) |
docker |
When your API is equipped with --add-docker the docker command speeds up some of the mundate tasks you would do while developing and testing the API in a docker container. |
integration |
When your service needs to use other services (whether remote or installed locally) you may find it convenient to separate the integration logic into its own module. That what integration is for. There are some built-in integrations (e.g. to AWS's S3), or you can start with a blank integration and roll your own. |
setting |
(coming soon) |
run |
This command launches your service. Call it anywhere in your service folder structure. |
You can view the above list by running hypermea with --help
hypermea --helpWith each command, add --help to see more details about that command
Tip
The
hypermeacommand is aliased to the shorterhyand you can use either interchangeably
hypermea api --help
hy api create --help