Connect your JHipster apps to the world of APIs with OpenAPI and gRPC

1. https://jhipster.tech @java_hipster
Connect your JHipster apps to the
world of APIs with OpenAPI and gRPC
+ +

2. https://jhipster.tech @java_hipster
Le me
● Working at Engie (but soon CDiscount)
● JHipster core team member
● Swagger-codegen former core team
member
● OpenAPI-generator core team member @cbornet_

3. https://jhipster.tech @java_hipster
Evolution of SOA protocols
RMI
CORBA
DCOM SOAP
REST
gRPC ?
AVRO
THRIFT
XML-RPC GraphQL ?

4. https://jhipster.tech @java_hipster
Today, everybody does REST...

5. https://jhipster.tech @java_hipster
Today, everybody does REST…
Richardson maturity model

6. https://jhipster.tech @java_hipster
Today, everybody does REST…
Roy Fielding : HATEOAS*
is a pre-condition to REST
*HATEOAS: Hypermedia As The Engine Of Application State

7. https://jhipster.tech @java_hipster
Today, everybody does REST… or not
In practice, this is the state
of the art, including
JHipster
“I am getting frustrated by the number of people calling any HTTP-based
interface a REST API.” - Roy Fielding

8. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?

9. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
CORBA-IDL
module BankDemo
{
typedef float CashAmount;
typedef string AccountId;
interface Account
{
readonly attribute AccountId account_id;
readonly attribute CashAmount balance;
void withdraw(in CashAmount amount) raises (InsufficientFunds);
void deposit(in CashAmount amount);
}
}

10. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
SOAP’s WSDL
<definitions name = "HelloService"
targetNamespace = "http://www.examples.com/wsdl/HelloService.wsdl"
xmlns = "http://schemas.xmlsoap.org/wsdl/"
xmlns:soap = "http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns = "http://www.examples.com/wsdl/HelloService.wsdl"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema" >
<message name = "SayHelloRequest" >
<part name = "firstName" type = "xsd:string" />
</message>
<message name = "SayHelloResponse" >
<part name = "greeting" type = "xsd:string" />
</message>
<portType name = "Hello_PortType" >
<operation name = "sayHello" >
<input message = "tns:SayHelloRequest" />
<output message = "tns:SayHelloResponse" />
</operation>
</portType>
<binding name = "Hello_Binding" type = "tns:Hello_PortType" >
<soap:binding style = "rpc"
transport = "http://schemas.xmlsoap.org/soap/http" />
<operation name = "sayHello" >
<soap:operation soapAction = "sayHello" />
<input>
<soap:body
encodingStyle = "http://schemas.xmlsoap.org/soap/encoding/"
namespace = "urn:examples:helloservice"
use = "encoded" />
</input>
<output>
<soap:body
encodingStyle = "http://schemas.xmlsoap.org/soap/encoding/"
namespace = "urn:examples:helloservice"
use = "encoded" />
</output>
</operation>
</binding>
<service name = "Hello_Service" >
<documentation> WSDL File for HelloService </documentation>
<port binding = "tns:Hello_Binding" name = "Hello_Port" >
<soap:address
location = "http://www.examples.com/SayHello/" />
</port>
</service>
</definitions>

11. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
REST
No need for an IDL, with
REST my API is dynamic
and self-describing...

12. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
REST
But you’re not doing HATEOAS !
...

13. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
So let’s document our API
with word/pdf/asciidoc/...

14. https://jhipster.tech @java_hipster
Why Swagger/OpenAPI ?
So let’s document our API
with excel/pdf/asciidoc/...
- Tedious to write
- Hard to find
- Inaccurate, errors, not
up-to-date
- Lots of boilerplate code to
write by hand from reading
the doc

15. https://jhipster.tech @java_hipster
From code to doc : springfox + swagger-ui
- No additional work
- Doc in sync with the code
- No errors (except in case of
Springfox bug)
- Easy to find

16. https://jhipster.tech @java_hipster
From doc to client SDK
● OpenAPI-generator (previously swagger-codegen)
○ generate client SDK in 50+ languages/libraries
○ supports Swagger v2.0 and OpenAPI v3.0
○ SDK for Spring-Cloud FeignClient
● Module generator-jhipster-swagger-cli
○ Module that wraps Openapi-generator to generate back-end clients in
JHipster
○ Next step : support React and AngularX front-end client

17. https://jhipster.tech @java_hipster
API-first development
● Write the OpenAPI spec first then generate server stub
code from it
○ early review feedback from peers and client developers (with PRs)
○ clear separation of WHAT vs. HOW
○ single source of truth
○ infrastructure tooling
● JHipster’s “API-First” option
○ configures the openapi-generator-maven-plugin to generate interfaces at
compile time from the OAI spec
○ supports OAI spec v3.0

18. https://jhipster.tech @java_hipster
gRPC
“gRPC is a modern open source high performance RPC framework that
can run in any environment. It can efficiently connect services in and
across data centers with pluggable support for load balancing, tracing,
health checking and authentication.”

19. https://jhipster.tech @java_hipster
gRPC vs HTTP-JSON
● API centered
● Built for performance
● Protobuf
○ binary format
○ strongly typed
● IDL built-in
● Strongly typed
● HTTP/2 by default
● 10+ languages
● Service discovery, load balancing, fault
tolerance, monitoring, tracing integrated
● Resource centered
● Built for simplicity
● JSON
○ text format
○ weakly typed
● IDL optional (OpenAPI)
● Weakly typed
● HTTP/2 optional
● All languages
● Service discovery, load balancing, fault
tolerance, monitoring, tracing with the
good framework (Netflix/Spring Cloud)

20. https://jhipster.tech @java_hipster
gRPC other nice features
● Bidirectional streaming
● Deadline propagation
● Cancellation propagation
● Async non-blocking / reactive JAVA implementation
● Flow Control (pull type with back-pressure) at the wire level (beware of OOME
!!)
● Reactive-gRPC extension
○ https://github.com/salesforce/reactive-grpc by Salesforce
○ Wraps gRPC’s reactive type into Reactor’s Mono/Flux types
○ Passes the Reactive-Streams TCK

21. https://jhipster.tech @java_hipster
gRPC in JHipster
● generator-jhipster-grpc module
○ actuator endpoints
○ entities
○ your own grpc services
○ uses reactive-grpc lib
● Next steps
○ integrate with the future JH “reactive” option for end-to-end reactive
services from gRPC client to DB.
○ finish security config
○ production features (service discovery, LB, tracing, …)
○ integration of gRPC-web ?

22. https://jhipster.tech @java_hipster
Questions ?
https://github.com/cbornet/generator-jhipster-swagger-cli
https://github.com/cbornet/generator-jhipster-grpc
https://github.com/OpenAPITools/openapi-generator
https://github.com/salesforce/reactive-grpc

23. https://jhipster.tech @java_hipster
More information on JHipster
Main website https://jhipster.tech
GitHub https://github.com/jhipster/generator-jhipster
Twitter https://twitter.com/java_hipster
Stack Overflow https://stackoverflow.com/questions/tagged/jhipster?sort=newest