Helium

Helium is a DSL for REST API specifications and also a Java API for processing descriptions written in this language. The main goal of this project is to create a single source of truth about some REST API. Taking a spec as an input, Helium generates a lot of useful stuff that can be used to rapidly develop REST clients.

Specification Example

note "Twitter REST API example"  type "UserProfile" message {

id long required
screen_name 'string' required
profile_image_url_https 'string' optional 
}
  service {

name 'Twitter API'
description 'Piece of Twitter API'
version 1.1
 location "https://api.twitter.com/${
version
}
"
 get "/users/show.json" spec {

  name 'Get user profile'
  description ''' 

Returns a variety of information about the user specified by the required user_id 

or screen_name parameter. The author's most recent Tweet will be returned inline when possible. 
 '''
  parameters {

 user_id long optional

 screen_name 'string' optional

 include_entities boolean optional
  
}

  response "UserProfile"

}
 
}
 

Documentation

The main idea is to keep the single source of truth about data structures and contracts used in interactions via your REST API.

After writing a Helium spec you'll get automatically generated tests for described API and will be able to generate useful source code. Generated tests validate received responses to match data structures described in the spec.

On our wiki you'll find information about

• how to write Helium specs
• what tests can be generated by Helium
• what source code Helium generates

Currently we support JSON, when generate API tests, and Java, when generate source code.

Both tests and code generation are implemented via Java API provided by Helium for processing specs. This API allows you to access all the types, services, and methods described in specification.

You may use Helium Java API directly from your Java code or utilize our Gradle plugin to integrate Helium spec with your Gradle project.

You can find an Android project integration sample in this repository.

Java API Examples

// read from string new Helium().from("service {
name 'Example Service'
}
").processBy(new Handler() {

public void process(Project p) {

  System.out.println(p.getServices());

}
 
}
);
  // read from file and generate POJOs new Helium().from(new File("twitter.spec"))
.processBy(new EntitiesGenerator(

 new File("/build/gen"),

 EntitiesGeneratorOptions.defaultOptions("com.example.twitter")
));

With Groovy :)

You can write the specification code directly in your client:

new Helium().from {

service {

  name 'Example service'

}
 
}
.processBy({
 Project p ->
println p.services 
}
 as Handler)

License

 Copyright 2013 Stanfy Corp.
Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software  distributed under the License is distributed on an "AS IS" BASIS,  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and  limitations under the License.