Spec-first API design dramatically tightens and improves the development feedback loop without wasting effort on artifacts that can't be used. The Jira Software team has used this approach very successfully to build APIs that we expose to both internal and external consumers. In this session, James Navin will walk you through the spec-first approach and demonstrate the benefits that it brings. He will also highlight some tools that can be used to implement a spec-first development approach.

1. JAMES NAVIN | PRINCIPAL DEVELOPER | ATLASSIAN | @JFNAVIN
Spec-first API development
Build better APIs faster

3. {REST}

4. {REST}
Swagger

5. THINK API FIRST

6. Picture this…
Lets go on a journey together

7. We need this super awesome
feature built.
YOUR PM

8. YOUR STRESS LEVEL

9. It needs a new REST API.
YOUR PM

10. YOUR STRESS LEVEL

11. We have internal and external
teams lined up already to use it.
YOUR PM

12. YOUR STRESS LEVEL

13. Oh - and it has to be done in the next
6 weeks in time for #summit
YOUR PM

14. YOUR STRESS LEVEL

15. Implementation-first
Pre-warp era

16. API Impl Consumer
Spec
Generates…
Generate from…
Validate mocks from…
Test against…
Feedback to…
PROVIDER CONSUMER

18. 1. Some initial Confluence API design

19. 1. Some initial Confluence API design
Collaborative
Get your input from your
team and iterate on an API
design.

20. 1. Some initial Confluence API design
Collaborative
Get your input from your
team and iterate on an API
design.
Its just text
You can’t use it in your dev
process. And neither can
your consumers.

21. 1. Some initial Confluence API design
Collaborative
Get your input from your
team and iterate on an API
design.
Its just text
You can’t use it in your dev
process. And neither can
your consumers.
Not a great
format for specs
Tables?
Code blocks (no comments)?
Dot points?

22. 2. Dev time!

23. 2. Dev time!
Its Alive!
The effort here results in a
working implementation.

24. 2. Dev time!
Its Alive!
The effort here results in a
working implementation.
Slow feedback
Could take days to get to
prod-ready code into PR.

25. 2. Dev time!
Its Alive!
The effort here results in a
working implementation.
Slow feedback
Could take days to get to
prod-ready code into PR.
Framework
leakage
Easy for frameworks to leak
into and influence your API
design at this point.

26. 3. Review

27. 3. Review
Wisdom of the
masses

28. 3. Review
Wisdom of the
masses
Noise for
reviewers
Your API is now spread
across multiple source
files. No easy way to grasp
the final API.

29. 3. Review
Wisdom of the
masses
Noise for
reviewers
Your API is now spread
across multiple source
files. No easy way to grasp
the final API.
Low-value
feedback
Likely to get feedback on
implementation details/style
more than API design.

30. 4. Test and validate

31. 4. Test and validate
Get your consumers
involved
If you are generating a Swagger/
OpenAPI spec, now you can
access it.

32. 4. Test and validate
Get your consumers
involved
If you are generating a Swagger/
OpenAPI spec, now you can
access it.
Hard to validate
How do you validate that
your implementation
matches your original
design?

33. 4. Test and validate
Get your consumers
involved
If you are generating a Swagger/
OpenAPI spec, now you can
access it.
Hard to validate
How do you validate that
your implementation
matches your original
design?
Something
broken?
Start that dev-review-deploy
loop again.

34. 4. Test and validate
Get your consumers
involved
If you are generating a Swagger/
OpenAPI spec, now you can
access it.
Hard to validate
How do you validate that
your implementation
matches your original
design?
Something
broken?
Start that dev-review-deploy
loop again.
This may be the first time your consumers get
access to your API…

35. Design
Implement
Implement Review Test
Feedback
Implement Review Test
PROVIDER
CONSUMER
Review
Integration
Blocked

36. Spec-first
The next generation

37. API Impl Consumer
Spec
Feedback to…
Generate from…
Validate mocks from…
Build against…
Validate with…
Generate from…
Feedback to…
CONSUMERPROVIDER

39. 1. Design your API as an OpenAPI spec

40. Usable artefact
Validate your implementation.
Consumers can validate theirs.
1. Design your API as an OpenAPI spec

41. Usable artefact
Validate your implementation.
Consumers can validate theirs.
Industry standard
Atlassian is a signatory to the
OpenAPI initiative.
1. Design your API as an OpenAPI spec

42. Usable artefact
Validate your implementation.
Consumers can validate theirs.
Industry standard
Atlassian is a signatory to the
OpenAPI initiative.
Tooling support
Editors, viewers, codegen,
validators.
1. Design your API as an OpenAPI spec

43. 2. Encode example interactions

44. Validated
examples
Interaction examples can be
validated against your spec,
creating a tight feedback
loop.
2. Encode example interactions

45. Validated
examples
Interaction examples can be
validated against your spec,
creating a tight feedback
loop.
Documentation
by example
These examples will help
your reviewers and your
consumers understand
your API.
2. Encode example interactions

46. Validated
examples
Interaction examples can be
validated against your spec,
creating a tight feedback
loop.
Documentation
by example
These examples will help
your reviewers and your
consumers understand
your API.
Usable artefacts
Can be used for contract
testing.
2. Encode example interactions

47. 3. Get review feedback

48. Tight feedback
loop
Measured in hours, not days.
3. Get review feedback

49. Tight feedback
loop
Measured in hours, not days.
Effective
feedback
Feedback is about your
API design, not your
implementation details.
3. Get review feedback

50. Tight feedback
loop
Measured in hours, not days.
Effective
feedback
Feedback is about your
API design, not your
implementation details.
Consumer
feedback
The spec is a great vehicle to
seek feedback from your
consumers - internal and
external.
3. Get review feedback

52. 4. Dev time!

53. Validate your
implementation
Use your spec to validate
that your implementation is
correct.
4. Dev time!

54. Validate your
implementation
Use your spec to validate
that your implementation is
correct.
Generate your
implementation
Tooling exists to generate
an implementation
direction from the spec.
4. Dev time!

55. Validate your
implementation
Use your spec to validate
that your implementation is
correct.
Generate your
implementation
Tooling exists to generate
an implementation
direction from the spec.
Gnarly
implementation
You may have unwittingly
made an API design decision
that is tricky to implement.
4. Dev time!

56. Design
Implement
ImplementReview Test
Feedback
Implement Review Test
Review
Integration
PROVIDER
CONSUMER

57. What is contract testing?
A 2-slide primer

58. Test against the API contract.
Not the real thing.

59. Consumer-driven
Consumer defines their
expectations.
Provider validates that the
implementation meets
expectations.
Provider-driven
Provider defines the API
contract.
Consumers validate their
usage against the contract.
Contract testing

60. The tools
Are here. Now.

61. https://tinyurl.com/spec-first

62. CREATE YOUR SPEC
IDE Plugins
VSCode, IDEA etc.
Syntax highlighting, schema
validation, code completion.
Swagger Editor
Purpose-built tool for editing
and previewing your spec
https://swagger.io/tools/swagger-editor/
https://github.com/arjun-g/vs-swagger-viewer

63. ENCODE YOUR EXAMPLES
Pact
JSON format for describing
request/response interactions.
Supported by the Atlassian
Contract Testing CLI.
https://docs.pact.io/

64. GENERATE YOUR IMPLEMENTATIONS
Swagger Codegen
Community-contributed
generators.
Generate implementation
skeletons and clients.
https://swagger.io/tools/swagger-codegen/

65. VALIDATE YOUR IMPLEMENTATION
Atlassian Contract Testing CLI
Language agnostic CLI tool for contract testing.
Validate mocks against an API spec.
https://bitbucket.org/atlassian/contract-testing-cli
Swagger Request Validator
Java library for validating request-response
interactions against an API spec.
Adapters for Pact, WireMock, RestAssured and
Spring MVC.
https://bitbucket.org/atlassian/swagger-request-validator

66. A quick recap

67. YOUR API IS THE THING
YOU’RE GOING TO HAVE TO
SUPPORT FOR A LONG TIME.
NOT YOUR
IMPLEMENTATION.

68. API Impl Consumer
Spec
PROVIDER CONSUMER
Feedback to…
Generate from…
Validate mocks from…
Build against…
Validate with…
Generate from…
Feedback to…

69. Tight feedback
loop
Measured in hours,
not days.
Effective
feedback
Focused on the API,
not implementation
details.
Minimal
wasted effort
All artefacts are
useful, and iterate
fast before large
investment.
Contract testing
Validate your
consumer mocks and
provider
implementation
The key benefits

70. Think API first. Do spec-first.
Emoji icons by Smashicons from www.flaticon.com; Licensed CC 3.0 BY.

71. Thank you!
JAMES NAVIN | PRINCIPAL DEVELOPER | ATLASSIAN | @JFNAVIN