https://github.com/hdpe/bowman
A Java library for accessing a JSON+HAL REST API
https://github.com/hdpe/bowman
hal rest-client spring-data-rest
Last synced: 5 months ago
JSON representation
A Java library for accessing a JSON+HAL REST API
- Host: GitHub
- URL: https://github.com/hdpe/bowman
- Owner: hdpe
- License: apache-2.0
- Created: 2016-08-31T16:04:52.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2024-10-04T20:27:19.000Z (over 1 year ago)
- Last Synced: 2026-01-14T01:47:00.834Z (6 months ago)
- Topics: hal, rest-client, spring-data-rest
- Language: Java
- Homepage:
- Size: 974 KB
- Stars: 47
- Watchers: 10
- Forks: 18
- Open Issues: 8
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= Bowman
image:https://github.com/hdpe/bowman/actions/workflows/build.yml/badge.svg?branch=main[title=Build Status,link=https://github.com/hdpe/bowman/actions?query=branch%3Amain]
image:https://coveralls.io/repos/github/hdpe/bowman/badge.svg?branch=main[title=Coverage Status,link=https://coveralls.io/github/hdpe/bowman?branch=main]
image:https://img.shields.io/maven-central/v/me.hdpe.bowman/bowman-client.svg[title=Maven Central,link=https://search.maven.org/#search%7Cga%7C1%7Ca%3Abowman-client]
Bowman is a Java library for accessing a http://stateless.co/hal_specification.html[JSON+HAL] REST API.
== Documentation
* https://hdpe.github.io/bowman/latest/reference/[Reference Documentation]
* https://hdpe.github.io/bowman/latest/apidocs/[Javadoc]
== Features
* *Simplified API consumption* via automatic, *lazy link traversal* on an *annotated client-side model*
* Tailor made for *https://projects.spring.io/spring-data-rest/[Spring Data REST]*
* *Analogous interface* to JPA
* *RESTful CRUD* and *templated link query* support
* *Polymorphic* deserialisation
Standing on the shoulders of http://projects.spring.io/spring-hateoas/[Spring HATEOAS] and https://github.com/FasterXML/jackson[Jackson].
== Usage Example
Given the following annotated model objects:
[source,java]
----
@RemoteResource("/people")
public class Person {
private URI id;
private String name;
public Person() {}
public Person(String name) { this.name = name; }
@ResourceId public URI getId() { return id; }
public String getName() { return name; }
}
----
and
[source,java]
----
@RemoteResource("/greetings")
public class Greeting {
private URI id;
private Person recipient;
private String message;
public Greeting() {}
public Greeting(String message, Person recipient)
{ this.message = message; this.recipient = recipient; }
@ResourceId public URI getId() { return id; }
@LinkedResource public Person getRecipient() { return recipient; }
public String getMessage() { return message; }
}
----
Client instances can be constructed and used as demonstrated below.
The HTTP requests/responses corresponding to each instruction are shown in a comment
beneath.
[source,java]
----
ClientFactory factory = Configuration.builder().setBaseUri("http://...").build()
.buildClientFactory();
Client people = factory.create(Person.class);
Client greetings = factory.create(Greeting.class);
URI id = people.post(new Person("Bob"));
// POST /people {"name": "Bob"}
// -> Location: http://.../people/1
Person recipient = people.get(id);
// GET /people/1
// -> {"name": "Bob", "_links": {"self": {"href": "http://.../people/1"}}}
assertThat(recipient.getName(), is("Bob"));
id = greetings.post(new Greeting("hello", recipient));
// POST /greetings {"message": "hello", "recipient": "http://.../people/1"}}
// -> Location: http://.../greetings/1
Greeting greeting = greetings.get(id);
// GET /greetings/1
// -> {"message": "hello", "_links": {"self": {"href": "http://.../greetings/1"},
// "recipient": {"href": "http://.../people/1"}}}
assertThat(greeting.getMessage(), is("hello"));
recipient = greeting.getRecipient();
// GET /people/1
// -> {"name": "Bob", "_links": {"self": {"href": {"http://.../people/1"}}}
assertThat(recipient.getName(), is("Bob"));
----
== Contributing
* link:./development.adoc[Development Guide]