Empathic API Design

CORNEIL DU PLESSIS

About Me●Programmer since 1985

●Smallest to very large systems.

●Cobol, Pascal, Algol, C/C++, Java, Scala, Groovy and other JVM languages.

●Scientific instrumentation, Sports event management, Mining, Banking, Treasury and Insurance.

●Software Architect (coding included)

Quote

The Opposite of Empathy is Contempt.

Anonymous

Introduction●What is an API?

●Considerations in API Design

●Why Empathy in API Design?

●Documenting your API

What is an API?Definition:

Application Programming Interface

Examples:

– C stdlib.h

– Java Standard Library

– Spring Framework

– Google Maps API

– Facebook Graph API

Considerations in API DesignQuote:

Everything should be made as simple as possible, but no simpler

Albert Einstein

Considerations in API DesignJoshua BlochPrincipal Software Engineer at GoogleHow to Design a Good API and Why it Matters

– Easy to learn

– Easy to use, even without documentation

– Hard to misuse

– Easy to read and maintain code that uses it

– Sufficiently powerful to satisfy requirements

– Easy to extend

– Appropriate to audience

Considerations in API Design●Simple

●Unambiguous

●Usage oriented

●Asset

●Discipline

Why Empathy in API Design?●When your audience doesn’t have an alternative.

●When your audience is human.

●Because they depend on it.

●Because they gave you money.

Documenting your API●Code is the document

●Tools

– Javadoc

– Doxygen

– Asciidoc

●Rest API

– RAML

– Swagger

– Spring Rest Docs

RAML●RESTful API Modeling Language

●RAML 0.8

– YAML

– Like RFC

●RAML 1.0

– YAML 1.2

– Template URI

– Data types

– Annotations

– Security Schemes

RAML#%RAML 1.0title: Spring Data Rest Demo APIversion: v1protocols: [ HTTP ]baseUri: http://localhost/apimediaType: application/jsontypes:

RAML - Typestypes:User:type: objectproperties:userId: stringemailAddress: stringfullName: stringdateOfBirth: date-onlyhasImage: boolean

Group:type: objectproperties: description: stringgroupName: stringgroupOwner: User

RAML – Operations/users:post:body:type: Userdescription: Create a User

responses:200:body:type: User

RAML - Operations/users/{id}:

get:description: Get a Userresponses:

200:body:

type: User404:

description: User doesn't exist/users/search:

get:queryParameters:

input:description: Sub string to matchtype: string

responses:200:

body:type: User[]

Swagger●Swagger 2.0

●JSON / YAML

●JSON Schema

Swagger – Springfox●Swagger from Annotations

●Spring MVC - Rest

●Swagger UI

Springfox - Configuration@EnableSwagger2@Configurationpublic class SwaggerConfiguration {@Beanpublic Docket swaggerSpringMvcPlugin() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());

}private ApiInfo apiInfo() {return new ApiInfo("Spring Data Rest Demo",

"Demonstrate Spring Data RestController","2","/",new Contact("Corneil du Plessis", "",

"corneil.duplessis@gmail.com"),"","");

}}

Springfox - Configuration@EnableWebMvc@Configurationpublic class WebApplicationConfiguration

extends WebMvcConfigurerAdapter {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry)

{registry.addResourceHandler("/swagger-ui.html")

.addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**")

.addResourceLocations("classpath:/META-INF/resources/webjars/");

}}

Swagger - Springfox@RequestMapping(path = "/users/{id}", method = RequestMethod.GET)@ApiOperation(value = "Get User")@ApiResponses({@ApiResponse(code = 200, message = "Success", response =

User.class), @ApiResponse(code = 404, message = "Entity Not Found")

})public ResponseEntity<User> getUser(@PathVariable("id") Long id)

throws EntityNotFound {User user = userRepository.findOne(id);if (user == null) {throw new EntityNotFound();

}return ResponseEntity.ok(user);

}

Springfox - UIDemo

Spring Rest Docs●Documentation driven by Unit Tests

– Asciidoc

– Snippets

– Conventions

– Test Methods

– Feedback on completeness

Spring Rest DocsDemo

ConclusionQuestions?

Resources

– https://github.com/corneil/spring-data-rest-angular-demo

– http://raml.org

– http://swagger.io

– http://springfox.github.io/springfox

– https://projects.spring.io/spring-restdocs