Ruby HTTP client generator for JSON APIs represented with JSON schema, forked from Heroics.
WARNING: Atum is currently in early Alpha development. You have been warned.
$ gem install atum
Atum generates an HTTP client from a JSON schema that describes your JSON API. Look at prmd for tooling to help write a JSON schema. When you have a JSON schema prepared you can generate a client for your API.
To see a simple example, you can look at the Fruity API json schema in Atum's spec fixtures
To generate a new rubygem client (for our ficitional Fruity API), you can run:
$ atum new fruity-api
This will does several things:
-
Creates a new gem called
fruity-api
in afruity-api
folder in the current directory
$ atum new fruity-api create fruity-api/Gemfile create fruity-api/Rakefile create fruity-api/LICENSE.txt create fruity-api/README.md create fruity-api/.gitignore create fruity-api/fruity-api.gemspec create fruity-api/lib/fruity/api.rb create fruity-api/lib/fruity/api/version.rb Initializing git repo in /Users/petehamilton/projects/atum/fruity-api ```
- Creates a
.atum.yml
file in the root of the gem and populate it with:You can add more configuration options to this file to prevent having to add lots of command line arguments later. See below.gem_name: fruity-api constant_name: FruityApi
Now you have a gem, you need to populate the lib directory. To do this, navigate to the root of your gem and run:
$ atum generate --file PATH_TO_SCHEMA --url API_URL
Note: You can store the file and url config in your .atum.yml file for convenience
If your client needs to pass custom headers with each request these can be
specified using --default-headers or -H
:
$ atum generate -H 'Accept: application/vnd.myapp+json; version=3'
To pass multiple headers, just give multiple strings:
$ atum generate -H 'header1' 'header2' 'header3'
You can also define a default_headers section in your .atum.yml file.
default_headers:
- Accept: application/vnd.myapp+json; version=3
- Accept-Language: Fr
The generated client has Yard-compatible docstrings. You can therefore generate documentation using yard
:
$ yard doc -m markdown .
This will generate HTML in the docs
directory. Note that Yard creates an
_index.html
page won't be served by Jekyll on GitHub Pages. Add a
.nojekyll
file to your project to prevent GitHub from passing the content
through Jekyll.
When an API returns an error, Atum will return an ApiError
.
Assuming the error response form the server is in JSON format, like:
{
"error": {
"documentation_url": "https://developer.gocardless.com/enterprise#validation_failed",
"message": "Validation failed",
"type": "validation_failed",
"code": 422,
"request_id": "dd50eaaf-8213-48fe-90d6-5466872efbc4",
"errors": [
{
"message": "must be a number",
"field": "sort_code"
}, {
"message": "is the wrong length (should be 8 characters)",
"field": "sort_code"
}
]
}
}
Atum will return an Atum::Core::ApiError error. You can access the raw hash (unenveloped) via a .errors
method, by default the error message will contain the error's message and a link to the documentation if it exists.
Atum only supports Ruby >= 2.0.0 out of the box due to our use of Enumerable::Lazy for lazy loading of paginated API resources.
However, support for previous ruby versions can be added using a gem such as backports.
- Add backports to your Gemfile
gem 'backports'
- Require lazy enumerables
require 'backports/2.0.0/enumerable/lazy.rb'
- Fork the repository
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new pull request