From 0de8a853b1b867b47fe334c7c17990de71281b09 Mon Sep 17 00:00:00 2001 From: David Johnston Date: Fri, 25 Apr 2025 22:19:59 +1000 Subject: [PATCH 1/2] Beyond documentaiton --- src/routes/drafts/beyond_documentation.mdx | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 src/routes/drafts/beyond_documentation.mdx diff --git a/src/routes/drafts/beyond_documentation.mdx b/src/routes/drafts/beyond_documentation.mdx new file mode 100644 index 00000000..c549627b --- /dev/null +++ b/src/routes/drafts/beyond_documentation.mdx @@ -0,0 +1,49 @@ +--- +meta: + title: Beyond an API and documentation - the artifacts a service should provide + description: If you're lucky, the service you're consuming might provide an API spec and a client SDK. I argue they could provide so much more. + dateCreated: 2025-04-01 +--- + +I'm a big fan of service boundaries. + +Whether we're consuming a third party service, say Stripe, which we have absolutely no control over, or an internal service being managed by others in the organisation we're working in, services boundaries allow us draw clear lines in the overall application, allowing us to compartmentalise our mental model. + +A popular form of service boundary is a REST API defined by an OpenAPI spec. For this post I'm going to assume a service of this type, but other service formats could be a a GraphQL API, an RPC style API or simply a client SDK. + +A service will typically come with API documentation, telling us the shape of request and response payloads. This documentation can be generated from the OpenAPI spec. Documentation tools like Stoplight.io can provide interactive documentation - that allows the developer to make real API requests as they read the documentation. + +Services may also publish their OpenAPI spec, so you as the developer can make use of it in your own tooling. + +Unfortunately, this is where services often stop, and I think they could do so much more. + +These are the things an OpenAPI based service could provide, along side the API itself and the documentation. + +The thesis here is that service providers not only should adhere to the service contract, they should also be considering how their clients are going to testing their application, as it relates to interactions with their service. + + +## A Postman collection + +To be fair, a lot of services do provide this. + + +## A Docker image for + +## For component library - test accessor functions + +This relates not to REST APIs, but component libraries. + +Say you have a component library that is providing a payment details form. + +If a user of the library is then trying to interact with this form in a test, this can be quite a tedious task. + +```js +//Testing library: +userEvent.write(screen.getByRole("textbox", {name: "Name"}), "Joe Bloggs") +userEvent.write(screen.getByRole("textbox", {name: "Credit Card Number"}), "1234 1234 1234 1234") +// and several more forms +``` + +Interacting with components like color pickers, dropdowns, items that select by clicking inside a tooltip, can all be similarly tedious, for the person who is just trying to add and item to a cart, or submit an order submission form etc. + +Service providers can help by providing convenience functions for use in the tests. \ No newline at end of file From 819f1903e6a42109b83e3668ff68774934c762af Mon Sep 17 00:00:00 2001 From: David Johnston Date: Wed, 2 Jul 2025 10:59:47 +1000 Subject: [PATCH 2/2] updates --- src/routes/drafts/beyond_documentation.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/routes/drafts/beyond_documentation.mdx b/src/routes/drafts/beyond_documentation.mdx index c549627b..394bd532 100644 --- a/src/routes/drafts/beyond_documentation.mdx +++ b/src/routes/drafts/beyond_documentation.mdx @@ -24,10 +24,14 @@ The thesis here is that service providers not only should adhere to the service ## A Postman collection -To be fair, a lot of services do provide this. +Many services do provide this. +A Postman collection is going to make it a lot easier exploring how to use the application. + +## A Docker image for running the application in a test mode. + +The idea here is -## A Docker image for ## For component library - test accessor functions