Contract Driven Development

Have you ever used a web-based API that was poorly designed and inconsistent? Have you found gaps between the documentation and implementation? At Patientco, we have successfully implemented a Contract Driven Design methodology for APIs. Swagger is used to design RESTful endpoints before a line of code is written and the specification, documentation, and code are kept in sync through automated testing and deployment.

Transcript

1. Contract Driven Development Chris Church Connect.Tech 2016
2. Me • Chris Church • Full Stack Polyglot Developer • Minecraft Sysadmin for my 3 kids • Home-brewer, Competitive Shooter, and Amateur Carpenter
3. Where I Work • SaaS Healthcare Payments Company • INC. 500 Listed Company • LAMP-ish • Director of System Engineering and Architecture • We’re hiring!
4. Talk Today • Overview of Contract Driven Development Approach • How we do CDD using Swagger and PHP • Goal: Make Better APIs
5. Why Better APIs? • Maintainability • Flexibility • Encapsulation • Reuse • We can’t make great software without great APIs
6. Swagger • Declarative specification for REST APIs • JSON or YAML • Large ecosystem of tools • Great for defining contracts!
7. Swagger Format • Swagger Editor • Examples • Echo • Twitter
8. Swagger UI • Publish your specification • Example
9. Swagger Mock Generator • PHP Silex Server • PHP Client
10. Swagger Assertions • github.com/Maks3w/SwaggerAssertions • How do you test that your API matches a Swagger spec? • Automatically validate the spec on every controller test
11. Example Test public function testGetDisbursedPayments() {
 //...
 $response = $this->get("api/v1/payments");
 $this->assertEquals(200, $response->code);
 
 $jsonContent = json_decode($response->content);
 $this->assertEquals($payment->id, $jsonContent);
 }

12. Example Test public function testGetDisbursedPayments() {
 //...
 $response = $this->get("api/v1/payments");
 $this->assertEquals(200, $response->code);
 
 $jsonContent = json_decode($response->content);
 $this->assertEquals($payment->id, $jsonContent);
 } 
 public function get($path, $input=array(), $validation=true) {
 return $this->request("GET", $path, $input, $validation);
 } public function request($method, $path, $post=array(), $validation=true) {
 //$request = ... $response = self::$app->process($request);
 
 if($validation) {
 self::validateRequest($method, $request->path, $post,
 json_decode($response->content),$response->code);
 }
 
 return $response;
 }
13. Example Test private function validateRequest($method, $path, $post, $response, $responseCode) {
 $swaggerSpecFile = self::$swaggerPath . self::$app->name . "-spec.json";
 
 if (file_exists($swaggerSpecFile)) {
 $swaggerAssert = new AssertsTrait();
 $schemaManager = new SchemaManager('file://'. $swaggerSpecFile);
 
 if ($schemaManager) {
 try {
 $swaggerAssert->assertRequestBodyMatch($post, $schemaManager, '/' . $path, $method, 200);
 }
 catch (Exception $e) {
 self::fail($e->__toString());
 }
 
 try {
 $swaggerAssert->assertResponseBodyMatch($response, $schemaManager, '/' . $path, $method, $responseCode);
 }
 catch (Exception $e) {
 self::fail($e->__toString());
 }
 }
 else {
 self::fail("Failed to load Swagger Schema Manager from " . $swaggerSpecFile);
 }
 }
 else {
 self::fail("Unable to load Swagger definition at ". $swaggerSpecFile);
 }
 }
14. More Swagger Assertions • Test Authentication • Versioning • Depends on versioning scheme • Contract coverage - like code coverage
15. What is CDD? • Contract Driven Development • TL;DS: Build APIs and API-centric applications by defining a contract first and developing code around mocks and schema validations
16. What is CDD? • TDD, BDD, DDD, ADD, YADD • Not really about contracts • The first steps determine the structure of the rest of the application.
17. Methodology 1. Define a rough API specification 2. Define use cases against API 3. Define error cases 4. Begin coding 5. Iterate coding and API changes
18. 1) Draft • High level pass over endpoints • Nouns • CRUD • Define Authentication • “Happy Path” responses
19. 1) Draft Brainstorming • GET /payments • GET /payments/<id> • POST /users • POST /tokens
20. 1) Draft Swagger • See Example
21. 2) Use Cases • API User Stories • Typically multi-call flows • Find • Missing endpoints • Missing data • Inefficient access patterns
22. 2) Use Cases Example 1. Request payment • POST /token 2. Check payment status • GET /payments/{referenceid}
23. 3) Error Cases • Decide on a standard convention for errors • HTTP Codes, Error Codes, Error Messages • Goal • Easy to understand • Easy to program against
24. 3) Error Cases • Identify internal and external causes • Invalid Inputs • Unknown Values • Invalid Access • Internal Errors • Put these into your API Spec
25. 3) Error Cases • Example
26. 4) Coding • Implement contract verification using Swagger assertions • Write tests calling (or simulating calls) to a controller, verifying response values, and using contract verification • Write controller logic until the test passes
27. 5) Iterate “No plan survives contact with the enemy” -Helmuth Von Moltke
28. 5) Iterate “No plan schema survives contact with the enemy” -Helmuth Von Moltke
29. 5) Iterate • Make changes to the contract and regenerate mocks • Decide if your organization needs to version these changes • Some contract changes will break tests • Change controller behavior until the tests pass
30. Post-Launch • Versioning your specification • Depends on how you version the API • Update API doc on deploy • Maintain schema validations on all unit and integration tests
31. Wrapping Up • There are lots of tools for APIs - leverage them • Design your APIs like a user interface • Think through interactions and expectations • Keep your tests, code, and documentation in sync with automation