Chasing the RESTful Trinity - Client CLI and Documentation

@radcortez @ivanjunckes @tomitribehttps://www.tomitribe.com/codeone/dev6001/
Roberto Cortez, Ivan Junckes Filho
Chasing the RESTful Trinity
Client, CLI and Documentation

Speakers
Roberto Cortez
● Senior Software Engineer at Tomitribe
● Java Champion & Oracle Groundbreaker
● JUG Leader Coimbra JUG & vJUG
● JNation Conference Founder & Organizer
● Blogger, Youtuber, Speaker
● +10 years of experience with Java
● Software Engineer at Tomitribe
● Oracle Certified Professional
● 9+ years experience with JavaEE
● Eclipse Commiter: JnoSQL, JPA, JSONB
and JSP
Ivan Junckes
● Memberof GUjavaSC

@radcortez @CesarHgt @tomitribehttps://www.tomitribe.com/codeone/dev6016/
Questions?
As soon as you have them!

Agenda
● REST API Development
● Problems
● Challenges
● Inget
● Future

REST API Dominates

REST API
● Most projects use REST now
● Stable Standards
● Repetitive
● Plenty of frameworks to use

Real Case
● Typical project with a REST API
● 2 years work
● 8-10 developers
● 100+ API’s
● CRUDs and Lists

Result?

Problems
● Different names to represent the same object
● Some uses prefixes, others don’t
● Different Collection types
● Booleans (is, get, set)
● Enums vs Strings

Problems
● PUT vs POST
● Read / Create / Update properties
● Return Status Codes?
● Plural or singular names?
● Headers / Path Params / Query Params?

And we were still missing...
● Client Libraries
● Documentation
● Command Line
● Versioning

Challenges
● Producing REST apis is less than half of the work
● Tooling around it is needed
● How are you going to call a service?
● How are you going to document it?
● Do you want to expose it non technical people?

More challenges...
1. Microservices evolve too fast
2. Maintenance requires too much effort
3. Changing or adding new interfaces will require changes in all the
tooling around it
4. Documentation is frequently out of date
5. Cost is too high

How to solve it
● Generation is the realistic solution
● Tool with Client, CLI and Documentation
● The client will help you call the services from different apps
● The Command-line Interface will help access the services without code
● Your services will have up to date docs

Benefits
● You only spend time with the things that really affect the business
● You can evolve fast without worrying about the impact in different
toolings
● Less maintenance
● Less cost

Inget
● Open Source, Apache License
● Code Generator Tool
● Maven Plugin
● Use your own source
● From the model or resources files

JavaParser
● Parse
● Analyze
● Transform
● Generate
● Java Code

JavaParser
CompilationUnit cu = JavaParser.parse("JavaFilename.java");
ClassOrInterfaceDeclaration klass = cu.getClassByName("ClassName").get();
klass.addField("Date", "date", Modifier.PRIVATE);
klass.addImport("java.util.Date");

Model
● Amazon style Model
● Separate classes for each operation
● Only expose the fields used
● Annotated Model class to generate required classes

Demo
Model Generation

Resources
● Generates interfaces
● JAX-RS Endpoint
● Support for Bulk, Filters and Pagination
● You can add your own endpoints

Demo
Resources Generation

Client
● Microprofile Typesafe client implementation
● Deals with everything required to call a resource
● Can be incorporated to other applications
● Works with Basic, Signature and OAuth2 (very soon) authentication

BabyStore
Spotify Desktop App
Netflix Web App
client
client
client
Tribestream API Gateway

Demo
Client Generation

Command-line Interface
● Airlift / Airline
● Executable binary
● Manual page (Man page)
● SSH Keys
● Easily build scripts to call microservices

BabyStore
CLI
Tribestream API Gateway
Command Line Interface (baby)

Demo
Command Line Generation

Documentation
● Generates the Open API file (json / yaml)
● Microprofile Open API
● AsciiDoc / Markdown from Open API
● HTML to publish the documentation

Demo
Documentation Generation

Limitations
● Requires the initial model
● Lacks configuration
● Additional plugins to generate OpenAPI files and docs
● Missing store for CLI

Future
● Generation of clients in other languages
● Generate from openapi file
● Simplify setup
● GraalVM Native Images for CLI
● CLI auto complete

https://www.tomitribe.com/codeone/dev6001
Thank you
Contact us @TOMITRIBE

Chasing the RESTful Trinity - Client CLI and Documentation

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a Chasing the RESTful Trinity - Client CLI and Documentation

Semelhante a Chasing the RESTful Trinity - Client CLI and Documentation (20)

Mais de Roberto Cortez

Mais de Roberto Cortez (14)

Último

Último (20)

Chasing the RESTful Trinity - Client CLI and Documentation