Coherent REST API design
•Descargar como PPTX, PDF•
2 recomendaciones•951 vistas
This document discusses contract-driven API design using Swagger and Pact. It introduces Swagger for defining provider contracts by specifying API endpoints and parameters. It then discusses using Pact for consumer-driven contracts, where consumers define expectations of responses from providers. It provides examples of defining pacts between a mapping service consumer and datastandard provider. It also demonstrates validating pacts by testing provider implementations meet consumer expectations.
Recomendados
Recomendados
Más contenido relacionado
Destacado
Destacado (20)
Similar a Coherent REST API design
Similar a Coherent REST API design (20)
Último
Último (20)
Coherent REST API design
- 1. - documentation and testing using Swagger and Pact Coherent REST API design
- 2. 2. Contact Information Frederik Mogensen Software Developer, Cloud Team Stibo Systems E: frmo@stibosystems.com L: linkedin.com/in/fmogensen
- 3. 3. Agenda Contract driven API design Provider contracts - with Swagger Consumer Driven contracts - with Pact
- 5. 5. APIs in a Microservice architecture Unstable / changingAPIs No type safety between services No developer confidence
- 6. 2 Provider contracts - with Swagger “ A Provider Contract is a description of a service offered by a provider” - Steven Smith https://dzone.com/articles/application-pattern-consumer
- 7. 7. Swagger Example The Petstore paths: '/pet/’: post: tags: - pet description: Add a new pet to the store consumes: - application/json produces: - application/json parameters: - in: body name: body description:Pet object that needs to be added to the store required:true schema: $ref: '#/definitions/Pet‘ responses: '405': description:Invalid input '200': description:successful operation '/pet/{petId}': get: tags: - pet summary:Find pet by ID produces: - application/json parameters: - name: petId in: path description:ID of pet to return required:true type: integer responses: '200': description:successful operation schema: $ref: '#/definitions/Pet' '404': description:Pet not found security: - api_key: []
- 8. 8. Why define service endpoints? API that are JSON first Documentation and clarity Server / Client code generation
- 9. 9. Iterative API first development Update Swagger Definition Generate Endpoints Implement functionality Test and validate API New demands for API
- 10. 10. Demo using Swagger and Postman
- 11. 3 Consumer-Driven contracts - with Pact “ A Consumer Driven Contract is a description of how a provider satisfies an aggregate of Consumer Contracts ” - Steven Smith https://dzone.com/articles/application-pattern-consumer
- 12. 12. Integration test in a Microservice architecture Characteristic Slow Easy to break Hard to fix Scales BADLY Lots of infrastructure Lots of set up False negatives Infrastructure Startup all services Populate Databases Mock away external services http://www.slideshare.net/bethesque/pact-44565612
- 13. 13. Pact tests Characteristic Fast Stable Easy to debug Reliable No extra infrastructure Low setup Scales linearly Contracts for only the needed stuff Consumer-driven contracts describes the complete set of functionality demanded by the current set of consumers. http://www.slideshare.net/bethesque/pact-44565612
- 14. 14. Pacts – The basics Consumer Provider Request Response http://www.slideshare.net/bethesque/pact-44565612
- 15. 15. Pacts – The basics Consumer Provider Request Response Request Response Pact Consumer Provider http://www.slideshare.net/bethesque/pact-44565612
- 17. 17. Pact Broker Mapping Pact Frontend Mapping Product Pact Mapping Product Login Pact Frontend Login Datastandard Pact Mapping Datastandard User Pact Login User Pact iPhone Login Pact Example Consumer publishes pact on build Provider gets all pacts from broker - on test
- 18. 18. Defining a Pact @Pact(provider = "Datastandard", consumer = "Mapping") public PactFragment createFragment(PactDslWithProvider builder) { return builder .given("datastandard-default") .uponReceiving("A request for category with id=1 in specific datastandard") .path("/dataStandards/dataId/categories/1") .method("GET") .willRespondWith() .status(200) .body( "{" + ""id": "1"," + ""name": "Toys"" + "}" ) .toFragment(); } Pact Consumer Provider http://www.slideshare.net/bethesque/pact-44565612
- 19. 19. Pact example { "consumer": { "name": "Mapping" }, "provider": { "name": "Datastandard" }, "interactions": [ { "producer_state": "datastandard-default", "description": "A request for category with id=1 in specific datastandard", "request": { "method": "get", "path": "/dataStandards/dataId/categories/1" }, "response": { "status": 200, "headers": { "Content-Type": "application/json" }, "body": { "id": "1", "name": "Toys" } } } ], "metadata": { "pactSpecificationVersion": "1.0.0" } } Pact Consumer Provider
- 20. 20. Validating Pact on Consumer side @Rule public PactProviderRule rule = new PactProviderRule("Datastandard","localhost",“1234",this); @Test @PactVerification("Datastandard") public void runTest() { // Path variables String datastandardId = "dataId"; String categoryId = "1"; DatastandardService datastandardService = new DatastandardService("http://localhost:1234"); Category category = datastandardService.getCategory(datastandardId, categoryId); Category expectedCategory = new Category().withId("1").withName("Toys"); Assert.assertEquals(expectedCategory, category); } Consumer Request Response Pact Consumer Provider http://www.slideshare.net/bethesque/pact-44565612
- 21. 21. Validating Pact on Provider side @RunWith(PactRunner.class) @SpringApplicationConfiguration(classes = LeapDataStandardApplication.class) @ContextConfiguration(classes = TestAppConfig.class) @PactBroker(BrokerProtocol = "http", BrokerHost = "docker-machine", BrokerPort = "80", ProviderName = "Datastandard") public class DatastandardControllerTest { @Autowired private DataStandardController apiController; private DataStandardDelegateController delegateController = mock(DataStandardDelegateController.class, Mockito.RETURNS_SMART_NULLS); @Before public void setUp() throws Exception { ReflectionTestUtils.setField(apiController, "delegate", delegateController); } @ProviderState(value = "datastandard-default", deferredResponseInMillis = 0) public DataStandardController shouldResponseCorrectForDefaultDataSet() { when(delegateController.getStandardCategory( eq("dataId"), eq("1") )) .thenReturn(new ResponseEntity<>( new Category().withId("1").withName("Toys"), HttpStatus.OK)); return apiController; } } Provider Request Response Pact Consumer Provider http://www.slideshare.net/bethesque/pact-44565612
- 22. 22. Problems that can be detected with Pact Change of the endpoint URL Change in the expected parameters Change in the response payload
- 23. 23. What is it not good for? Performance and load testing. Functional testing of the provider Should be done by provider's own tests Pact is about checking the contents and format of requests and responses.
- 25. 25. References, documentation and more… github.com/realestate-com-au/pact martinfowler.com/articles/consumerDrivenContracts.html slideshare.net/bethesque/pact-44565612 slideshare.net/evanbottcher/from-monoliths-to-microservices-at- realestatecomau techblog.newsweaver.com/why-should-you-use-consumer-driven- contracts-for-microservices-integration-tests/ dzone.com/articles/application-pattern-consumer
Notas del editor
- In this talk we look at using Swagger and Pact to handle REST API specifications and contracts. Swagger allows for a JSON first specification of the API as well as generating and discovering service controllers. This can be done coherently across multiple technology stacks. We will look into using Pact to create consumer driven contract between services in a micro service architecture to improve development confidence.
- Different consumers of services -> JSON / XML Ever evolving microservices we need to change the API Problem senario 1. Provider service is being updated to a new version 2. It is behaving perfectly 3. But suddenly a number of other services start behaving incorrectly
- JSON FIRST: Not just what ever the given framework produces at a given time CODE GEN: Server - Java - C# - C - Ruby - Node - PHP Client - Android - Java - Dart - Perl - Akka scala - Swift - Ruby
- http://Docker-machine/api/v1/excel/swagger-ui.html http://docker-machine/api/v1/excel/v2/api-docs
- 1. The consumer defines what it expects from a specific request to a service 2. The provider and the consumer agree on this contract 3. The provider continuously verifies that the contract is fulfilled
- E.g. renamed endpoints E.g. new mandatory fields Returns an array, instead of having an array wrapped in an object Clearly API-breaking changes. May not be obvious that a code change changes the API. - Renamed Class / Field that are later JSON serialized It may also not be clear which Consumers are affected by code changes.