Skip to content
Build type-safe fluent-style JSON REST API clients in Java
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.
annotations
archetype
core
doc
parent
vaadin
.gitattributes
.gitignore
.travis.yml
LICENSE
README.md
appveyor.yml
pom.xml

README.md

TypedRest for Java

API documentation Build status
TypedRest helps you build type-safe fluent-style REST API clients.

Maven artifacts (group com.oneandone):
typedrest-annotations typedrest-core typedrest-vaadin typedrest-archetype

Important: Lombok, a build-time dependency, does not support Java 10 yet. However, the resulting artifact will work on Java 10.

Nomenclature

We use the following terms in the library and documentation:

  • An entity is a data transfer object that can be serialized (usually as JSON).
  • An endpoint is a REST resource at a specific URI.
  • An entry endpoint is an endpoint that is the top-level URI of a REST interface.
  • An element endpoint is an endpoint that represents a single entity.
  • A collection endpoint is an endpoint that represents a collection of entities and provides an element endpoint for each of them.
  • A trigger endpoint is an endpoint that represents an RPC call to trigger a single action (intentionally un-RESTful).

Usecase sample

We'll use this simple POJO (Plain old Java object) class modeling software packages as a sample entity type:

class PackageEntity {
  private int id;
  @Id public int getId() { return id; }
  public void setId(int id) { this.id = id; }

  private String name;
  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
}

Getting started

Include this in your Maven pom.xml to use the library:

<dependency>
  <groupId>com.oneandone</groupId>
  <artifactId>typedrest-core</artifactId>
  <version>0.30</version>
</dependency>

You can then use the classes EntryEndpoint, CollectionEndpointImpl, ElementEndpointImpl, PollingEndpointImpl, ActionEndpointImpl, PaginationEndpointImpl, StreamEndpointImpl and BlobEndpointImpl to build a local representation of a remote REST service. Based on our usecase sample this could look like this:

class SampleEntryEndpoint extends EntryEndpoint {
  public SampleEntryEndpoint(URI uri) {
    super(uri);
  }

  public CollectionEndpoint<PackageEntity> getPackages() {
    return new CollectionEndpointImpl<>(this, "packages", PackageEntity.class);
  }
}

You can then perform CRUD operations like this:

SampleEntryEndpoint server = new SampleEntryEndpoint(URI.create("http://myservice/api/"));
List<PackageEntity> packages = server.packages.readAll();
ElementEndpoint<PackageEntity> element = server.packages.create(new PackageEntity(...));
PackageEntity pack = server.packages.get(1).read();
server.Packages.get(1).update(pack);
server.Packages.get(1).delete();

Build GUI clients

Include this in your Maven pom.xml to build GUIs with Vaadin:

<dependency>
  <groupId>com.oneandone</groupId>
  <artifactId>typedrest-vaadin</artifactId>
  <version>0.27</version>
</dependency>
You can’t perform that action at this time.