This document discusses API design and emphasizes the importance of empathy in API design. It provides considerations for designing easy to use and learn APIs. Examples of API documentation tools are also presented, including RAML, Swagger, Spring Rest Docs, and Javadoc. The document recommends that APIs be simple, unambiguous, usage-oriented, and easy to extend. It encourages API designers to consider their audience and ensure APIs are easy to use, even without documentation.

1. Empathic API
Design
CORNEIL DU PLESSIS

2. 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)

3. Quote
The Opposite of Empathy is Contempt.
Anonymous

4. Introduction
● What is an API?
● Considerations in API Design
● Why Empathy in API Design?
● Documenting your API

5. What is an API?
Definition:
Application Programming Interface
Examples:
– C stdlib.h
– Java Standard Library
– Spring Framework
– Google Maps API
– Facebook Graph API

6. Considerations in API Design
Quote:
Everything should be made as simple as possible, but no simpler
Albert Einstein

7. Considerations in API Design
Joshua Bloch
Principal Software Engineer at Google
How 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

8. Considerations in API Design
● Simple
● Unambiguous
● Usage oriented
● Asset
● Discipline

9. 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.

10. Documenting your API
● Code is the document
● Tools
– Javadoc
– Doxygen
– Asciidoc
● Rest API
– RAML
– Swagger
– Spring Rest Docs

11. RAML
● RESTful API Modeling Language
● RAML 0.8
– YAML
– Like RFC
● RAML 1.0
– YAML 1.2
– Template URI
– Data types
– Annotations
– Security Schemes

12. RAML
#%RAML 1.0
title: Spring Data Rest Demo API
version: v1
protocols: [ HTTP ]
baseUri: http://localhost/api
mediaType: application/json
types:

13. RAML - Types
types:
User:
type: object
properties:
userId: string
emailAddress: string
fullName: string
dateOfBirth: date-only
hasImage: boolean
Group:
type: object
properties:
description: string
groupName: string
groupOwner: User

14. RAML – Operations
/users:
post:
body:
type: User
description: Create a User
responses:
200:
body:
type: User

15. RAML - Operations
/users/{id}:
get:
description: Get a User
responses:
200:
body:
type: User
404:
description: User doesn't exist
/users/search:
get:
queryParameters:
input:
description: Sub string to match
type: string
responses:
200:
body:
type: User[]

16. Swagger
● Swagger 2.0
● JSON / YAML
● JSON Schema

17. Swagger – Springfox
● Swagger from Annotations
● Spring MVC - Rest
● Swagger UI

18. Springfox - Configuration
@EnableSwagger2
@Configuration
public class SwaggerConfiguration {
@Bean
public 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"),
"",
"");
}
}

19. Springfox - Configuration
@EnableWebMvc
@Configuration
public class WebApplicationConfiguration
extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry)
{
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}

20. 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);
}

21. Springfox - UI
Demo

22. Spring Rest Docs
● Documentation driven by Unit Tests
– Asciidoc
– Snippets
– Conventions
– Test Methods
– Feedback on completeness

23. Spring Rest Docs
Demo

24. Conclusion
Questions?
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