Often we as developers hand craft REST APIs, that can be cumbersome. Requirements shouldn't be copied to code, either for tests or production. In my talk I want to stress that we can have a better workflow with REST API specification projects, than the usual one. I held this at bedon conference 2015 http://bed-con.org/2015/

1. @mrksdck
Design & Test First
Workflow For REST APIs
How can REST API specification projects help us?

2. @mrksdck
“hand copy” workflow
design
code
test
document

3. @mrksdck
“hand copy” workflow
design ≠ code ≠ test ≠ document
:(

4. @mrksdck
need for a better workflow
less error prone
easier specification implementation
specification can be changed

5. @mrksdck
REST API specification projects
api blueprint raml swagger

6. @mrksdck
helpful tools
designing
coding
testing
documenting

7. @mrksdck
designing
web - / text - editors
syntax highlighted
wysiwym
validator

8. @mrksdck
coding
generate
server
client
models

9. @mrksdck
testing
write client & server tests
validate implementation
import in tools e.g. postman

10. @mrksdck
documenting
dynamic
static

11. @mrksdck
tools are here to help
→ generate test server
→ generate test client
→ code
→ validate implementation
→ document

12. @mrksdck
“tooled” workflow
design
test
code
document

13. @mrksdck
“tooled” workflow
design = test = code = document
:)

14. @mrksdck
swagger as an example
swagger spec
swagger editor
swagger codegen
swagger ui

15. @mrksdck
swagger spec
write in editor
generate from annotated code
put into version control system
use as exchange document

16. @mrksdck
swagger spec

17. @mrksdck
swagger spec

18. @mrksdck
swagger editor

19. @mrksdck

20. @mrksdck
swagger codegen
possible targets
android, async-scala, csharp, dart, flash, java, jaxrs,
inflector, nodejs, objc, perl, php, python, python3,
qt5cpp, retrofit, ruby, scala, scalatra, silex-PHP, sinatra,
spring-mvc, dynamic-html, html, swagger, swagger-yaml,
swift, tizen, typescript-angular, typescript-node, akka-
scala, CsharpDotNet2

21. @mrksdck
swagger codegen
implement generated interfaces
use generated clients in tests
get to know different frameworks

22. @mrksdck
swagger ui
reads swagger.json
dynamic html page
try out

23. @mrksdck
swagger ui

24. @mrksdck
swagger ui

25. @mrksdck
swagger ui

26. @mrksdck
swagger ui

27. @mrksdck
“tooled” workflow
design
test
code
document

28. @mrksdck
artefact relations
design
test code document

29. @mrksdck
automation
design swagger-validation
test
code assertj-swagger
document swagger-codegen

30. @mrksdck
“tooled” workflow
design = test = code = document
:)

31. @mrksdck
“design and test first” - workflow
design = test = code = document

32. @mrksdck
Thank you for listening
Questions?

33. @mrksdck
References
examples are taken from swagger.io
http://petstore.swagger.io/
http://editor.swagger.io/
http://github.com/swagger-api/

34. @mrksdck
related blog posts
http://swagger.io/writing-apis-with-the-swagger-inflector/
http://blog.raml.org/guest-post-api-first-with-raml-development-and-
documentation-of-rest-apis/