Empathic API-Design
Download as PPTX, PDF1 like379 views
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.
![RAML
#%RAML 1.0
title: Spring Data Rest Demo API
version: v1
protocols: [ HTTP ]
baseUri: http://localhost/api
mediaType: application/json
types:](https://image.slidesharecdn.com/empathic-api-design-170529202719/85/Empathic-API-Design-12-320.jpg)
![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[]](https://image.slidesharecdn.com/empathic-api-design-170529202719/85/Empathic-API-Design-15-320.jpg)
Empathic API-Design
- 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", "", "[email protected]"), "", ""); } }
- 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); }
- 22. Spring Rest Docs ● Documentation driven by Unit Tests – Asciidoc – Snippets – Conventions – Test Methods – Feedback on completeness
- 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