Introduction to OpenAPI • Lorna Jane Mitchell • GOTO 2019

[Music] morning I have one very important thing to do before I start her when she's checked that my click is working oh it is it was just slow last time I gave a talk the buttons were reversed it's incredibly surprising how difficult I found that to deal with so let's see if we can keep this moving in a forward in a forward mother's day good morning thanks for coming I'm painfully aware that there are other excellent talks in this slot so I'm excited that there's anybody here at all I'm really glad you are here because I think this is a super interesting topic and something that is changing my working practice in lots of ways so I'm very excited to be here and very excited to share it with you my name is Lorna I'm a developer advocate with a company called next MOU we are we do communication api's we're in the middle of rebranding to vonage my whole slides say next MOU because my mouth will also say next MOU I will be working on this in the break between conference seasons so um can I just get a quick show of hands and I promise not to do this too many times who has already heard of next mo okay that would be the three people I was talking to in the bar last night awesome so why am I here speaking about open API s and about api's and about open API in particular I think api's are so key to the way that we develop software today whether we are integrating with third-party api's or whether we are connecting our components within our own applications there's a whole lot of API calls going on I'm speaking mostly about HTTP api's by using API descriptions like open API we can really powerup and enable our API workflows so today I want to tell you about open API and show you some examples of what you can do with it how it's changed things for us how this glue of inter application communication can really come up to the next level and how the tools can help us in our technical practice the big thing that I feel is enabled by API descriptions is spec first API design I've been on a conference circuit many years I've been working in API is for many years and I used to give a talk about Docs first API design once upon a time not that long ago I guess really I went to work to discover that a client for whom we ran an admin back-end system with a web interface they had a marketing website which had some read access to some views on the database I had a ticket open saying please grant read/write access so I started with no and I moved quickly on to what problem are we really solving what is this the solution for and they wanted to take some tentative bookings from the front end through their marketing a website which is completely reasonable and the deadline for this was yesterday so I swiftly wrote some API documentation and circulated it to their team now what's cool about doing Doc's first is it involves all of your stakeholders so even the people who can't create or use an API product people tech project leads delivery managers can all interact with documentation right it's aimed at humans also when as an engineer when I took my writing hat off put my engineer hat on it was a really small company and when I came to build the thing I've never built something so quickly because it was so well described already fast forward five years and spec first gives me all of this and more by creating an API description I can generate documentation I can involve all the stakeholders everything that was true about Doc's first is true about spec first but I can also generate a mock server the stubs of the API that I'll publish the SDK for the different stacks that we need to consume this thing and I can do it all off a single source of truth and whether you're designing a new API or just adding a feature leading with the spec allows everybody involved with the project to interact with it in a way that makes sense to them I do generate the docs and share it with the product people the engineers use that as well but when I'm really thinking about the API standards and whether we want to accept the patterns that we're proposing in this version of the spec I spin up a mock server and I poke at it with my favorite HTTP client exactly as I would as an engineer like what's this gonna be like to use what does it really mean I'm often asked where the open API is appropriate for existing api's or if it's something that really you should lead with on your next new project so new API is existing API is my advice is yes at next mo we are a mix so we retrofit the open API descriptions on all of our existing api's that isn't always easy open API is pretty modern and awesome so if you have gnarly terrible legacy API practices you'll find it hard to use open API in places it's like a code smell it's a spec smell not really sure what the analogy works there but for new API is for new features to existing API is that you've gone to the trouble to describe it's incredibly valuable so I am yes and yes on this question on both sides today is about open API it's not the only game in town so if you have heard of API blueprint or Rommel from mil soft who I think now have open API support or open API I think a lot of these principles still apply spec first design surprised using your spec as your source of truth still applies the syntax looks different the tooling is different if you have used an older API description protocol called swagger this was donated to the community there's a foundation Salinas Foundation project we have people set up to look after it and they are individuals from all kinds of organizations some not from an organization at all some from big organizations some from small organizations so we have a raft of people looking after this open standard which has had a new release version 3 it's not that new now it hasn't been called swagger for about 4 years please try to keep up so open API that well-known opened open standard and the thing about an open standard is we are all free to participate in that to see what's going on inside it you know the issues are public the meetings are public there are slack channels you can find out what's going on and I think the openness gives all kinds of organizations confidence in adopting something like this it doesn't belong to a company the standard won't suddenly change to match one corporations priorities because nobody really has that critical mass it's owned by all of us and the open standard leads to some excellent open tooling you want to build a tool build a tool you're you're welcome to do that and that gives us choice it gives us competition it gives us solutions available in all sorts of texts acts including SEM I had no idea we needed but somebody did and that's the point of having it open like this I'm going to speak now about some of the details of open API and how it looks maybe some of you don't love slides and slides of Yammer but some of you need to know how the engine works before you can drive the car we all have different learning styles so if you need to know how it works the next five slides are for you if you don't want to look at five slides of Yammer why don't you just tweet what a great time you're having and come back to me in five minutes okay fantastic all right this is the top section of an open API spec you can use JSON or Y amel this one is yeah Mille I could argue passionately for or against JSON or yeah Mille right there are no really good solutions this is designed for machines not for me we use Yammer it doesn't annoy me at all I think sometimes the get difts are a bit tidier that's my best so we've got open api the version of the open api specification that we are following the servers arrey arrey so if you have multiple endpoints for redundancy for sandboxes for geographical reasons cool glist them all here now we have the info block it's very easy to skate over the info block a lot of the tooling doesn't necessarily render it or doesn't render all of the fields this is a real open API spec if it wasn't it would be more perfect I haven't quite got if just fixing everything wanna use it a slide deck ever to-do list after seeing this one so this is our number insight API it's next most simplest API you give it a phone number and it tells you the phone numbers valid and how it should correctly be formatted and we also have basic standard and advanced levels which give you increasingly more details for increasingly higher cost and it's like fractions offense so now you know everything about this API it's easy to understand the info block is important because some day not too far in the future we are going to do more than render documentation from our open API descriptions we are going to upload our spec files to directories and catalogs users will discover our API is this way they will be looking for something and they will come to find what we have to offer and just like your projects and your website everything else that only works if the metadata is there so take the time with the inflow block lots of people just like on github we see people searching with a specific license right the same for this get all of this data in the right place and make sure it's complete because we'll be using this especially the keywords and the description that I cut off horribly because I didn't want to make the font any smaller than this and if you're a long way back I still feel like I owe you an apology so this is the top part these top level level elements open API servers info will be present in every open API spec file the next element is called paths now I've ripped out the guts of this to just give you an outline of how this works you're already starting to get the impression that these files might be reasonably long-winded I'm not gonna lie there thousands of lines of Yama usually this one is at least hundreds and it's the smallest smallest API we have we have the paths element within paths we list each of our endpoints and there can be variable parameter placeholders in there you can see it here with the format and then we list which verbs this endpoint supports it's just a lookup service that's not that interesting but that's what that get is doing every operation has an operation ID name your operation IDs carefully they get used in the most unexpected places obvious places like you'll see it when I show you the doc stuff later that it's used as the internal hyperlink name cool um it can be also used as the method naming and generated calls and that kind of thing so just try to give it a unique tag that's gonna mean something to you in any context just be a little bit careful with that within each of these individual paths each operation will also have parameters so these are the either body or query parameters that we're going to supply to this particular API call you'll also see responses so here we can detail the the status codes that might be expected for each of those the content types that might be expected and then the details within each of those so it gets it gets quite long-winded but it's very very descriptive every aspect of your API is described here another thing worth mentioning in addition to parameters and responses is that you'll also see callbacks so if your API call for example the the third one down advanced async format you give the parameters and the URL you'd like the results to don't call it synchronously it basically always fails call it asynchronously and then as a result you'll get a payload back and that's documented as a callback operation within the open API spec we don't yet have support for incoming HTTP requests that are triggered by something else well you don't subscribe or perform the event that makes it happen from inside the API but there's an open proposal for it and some of the tools have support already so if you're interested in web hooks callbacks open API stuff please talk to me about that I'm working on a proposal so if I understand your use case as well this would be a great time to talk to me about that it's or anything else I need to tell you here no okay so let's look at one of these in detail here's the basic call this parameters and there's responses the varieties we have format we have number we have country and you will immediately notice that there's no details here this stuff is a pointer to another location this is one of the magical pieces about open API this particularly for someone who's had experience of writing markdown documentation and there's a lot of copy-paste if you have to generate all this stuff by hand this is compiler assisted if you like the generators will go and look this stuff up and bring the details in when they need them so open API supports this reference and you can ref to other sections of the same spec and you can ref two sections of other files so if you have a few api's that share common for example we share common error format between our newer api's or if your file is just too large which is not that unusual then you can you can rest out so that's parameters his responses you're gonna get 200 response with an okay and the content is gonna be either JSON or XML and the responses are described again away in a ref I think there's a style question here when you write an open API spec should you always use a ref to keep things tidy so a human could read like a hole endpoint in one screen should you only use the component section or another reference when you reuse a variable I don't know the answers we're about to work on a style guide but I feel that there's a lot there's a lot that we haven't settled the conventions yet and the answers probably depend on your use case alright one more here's what's inside the ref this is that format parameter that's in the path it's required but there's no default you must specify it on every API call in this API it's called format it goes in the path it's always required it says what format the response should be the example is JSON it's a string it can be a JSON or it can be a XML so you get this very detailed description if there are rules about data types limits length limits integer ranges negative them was allowed all of that goes here we can describe all of those parameters in great detail but what's nice about this is I didn't have to have these ten lines in every endpoint in my spec if we suddenly add support for protobuf right whatever I just have it here and in boom it's everywhere and that's really nice I think it really open API is not just about publishing api's it's about maintaining them it's about keeping everything in sync when we deliver all of these artifacts that relate to the API that we've built Wow you made it thanks for staying with me that is a lot of Yama and it's not always the easiest thing to work with especially if you are new to this stuff there are tools to help you it would be much more sensible just to play the video so let's do a live demo let's have a look here we go cool so here is this is Adam it's just an ordinary editor this one's from github it's cross-platform I have got some gamal syntax highlighting plugged in so that lets me see when I've made a syntax mistake it'll put a little error if my indentation is incorrect and I can expand and collapse things which makes this a bit more readable so I can just pop into the basic format I also do a lot of find like jumping to find so I think the editor you already have is a really good starting point because you're already expert in that editor I'm a VM user and thousands of lines of ya Mille might seem ridiculous in vim but actually I has two necks I like half code folding I drop a lot of marks I'm pretty productive really I find it works pretty well so you have some options a really important thing here it is a text based specification you will not pass go or collect 200 pounds until you have checked your spec into your source control system and you have committed often yes I just stood on stage in a room full of tech experts and told them to use git I am NOT sorry it's amazing like we're firing all kinds of stuff off our git commits because we can diff so easily and when the version number changes things happen there's a whole separate talk but just commit it to source control you will thank your past self there are also some dedicated like custom tools around so for example this is stoplight studio we're going to hear the word stoplight a lot they're a company who offer a free desktop editor and a web also a web version of the same thing they publish a load of open-source tools around this space they make money from selling you even more awesome things that you could pay for other the entry-level things are available so you can get started with this there's no reason not to I've turned up the font size which has mainland layout a bit less pretty than normal and but on the Left we've got the specs that are in my projects so that's a local git clone the changes that I make are just on my desk if I can commit them back to get hub in the usual way it there's a list at the end points that it knows about in the middle I've got the this is the forms view I like to think of it is the human's view so this is where we can look at the different parameters and stuff that goes into this particular endpoint and drill into more detailed objects further over on the right hand side we've got the actual yam all that were outputting which can be quite useful to see and also a list of validation errors or feedback I've got some warnings here about tags I think the big feature here that one of the reasons that brings people to stoplight studio and keeps them here is the validation so it's quite nice to have it here I guess in the editor we go here and drill down for the schemer and say oh yeah this is within this file and we can jump in and look what it is look at the examples very nice the validation that's happening here and on the web version is driven by an open source tool published by stoplight called spectral so if you'd rather use your edited editor then you can just run that locally so here's spectral in action it's just wrapped in a shell script so you have to watch me type I've fed it that number inside Tatjana file as you can see it's quite angry about very many elements of it spectral by default is opinionated it is more than a validator right it's got lots of thoughts about what is the right way to do open API set you can define your own real sets you can make additional rules of your own so we have API standards and they are written down before we release of API a human reads the written standards and looks at the API and then says oh I think you've named that field incorrectly our rules of the things should be I can't remember maybe give up case I could automate that and then we could have it on the build as we're working on new specs or our new features so spectral is the tool for that I am always turning things on and off so I just turn off these arguments about what data type my example should be I mean I'll fix it someday but I haven't yet and I don't want to see those build failures so instead I can run in here spectral lint turning off a couple of those failing rules and the path to the specs that I'm interested in it detects open API 3 and shows me those for operation tags warnings that you saw in stoplights to do so we can use whichever tools we want to here are the slides in the deck so you can download this later and get all this again look whoo spectral so that's great we figured out how to handle thousands of lines of yeah Mille how to validate it how to style check it how to wrangle it it can be a bit verbose sometimes we've explained our API we've described it in great detail so that even the machines can understand what we've built yeah so now what what kind of machines do for us now we've gone to all this trouble to explain our products for them well we've got some options and I'll start with the easy one and that's documentation use your open API spec as the source of truth for your API reference Docs there's a choice of tools there are a few commonly used ones but there are lots of options you can publish right out stop light if you want to one of the big open source tools is redock we have our own next mode it's also open source so you can use that and you want your reference Docs to look like next moment because this the open API spec format encourages not just supports encourages examples it enables you to specify examples for individual fields but you can also give a whole example response if you want to it lends itself wonderfully well as a source for documentation and because we're generating the output independently of the API description you can output a bunch of different things I mean for the most part we're gonna output web HTML reference Docs awesome I've also output PDF ones from a top-secret branch which has a feature on the only very high paying customers can have currently because not scaled up enough it'll be in the next version of the API we don't want to publish that publicly because it'll confuse people who can't have it yet so I generated PDF off my open API spec that time around I've also seen some nice implementations that have like a cheat sheet doesn't show all the data that you've seen here it just shows a list of endpoints and they're supported methods and maybe a list of parameters just to kind of remind you what what you need to call here without having to wade through the whole thing so you can take these specs and you can generate a bunch of different outputs let's look at some examples so here's redock it's a JavaScript tool really well known it looks like this it just takes this back and generates me some documentation you don't have to do anything to get this other than write the spec and run the install the thing from NPM it describes the endpoint here's the query parameters here's the response parameters this is what the response looks like here it's using the individual example fields the example values from all the fields to generate the response that you should expect so instantly you can see what the payload would be coming back from this I promised you more than one tool so let's look at next Mo's open API renderer this is a ruby gem that you can just install either use it inside your Ruby application or use it standalone again again you can just it generates this here's all the variables you can pass in here's the responses you can see the example response on the right looking terrible because I've turned at the font size so far look at it on your own monitor it makes much more sense at a normal font size one of my favorite things about this is it's so much more than documentation I don't expect API providers to be like well we use open API so we're awesome I expect them to provide you that spec so you can be more awesome so see the big download open API 3 definition button this is where the magic starts so we can download this file and then we can use it in tools of our choice my favorite example right now is postman which align around here somewhere there we go so I just downloaded that file and I can import it into postman know this button this button excellent there it is awesome so here is the number insight spec as a postman collection so I've got example requests saved in postman for all of the endpoints that were in that API so as a developer who's looking at a new API or a stress Deverell person who is unfamiliar with this product that I have to immediately provide support for I'm sure I've seen this API before but I forgot something then you know we're here and I can immediately start to play with it so where's my API key here we go we can just add some stuff and make some calls this is my phone number this is my country code postman does not correctly import multiple security schemes so I'll just manually add the API secret which is of course highly secure if anyone sees me at lunchtime theater mightor would delete this secret oh okay mmm and I'd like that in JSON format and you can see it building the query string at the top there so if I send this request wish me luck with the Wi-Fi [Music] imagine a wonderful response Oh Oh hotspot login is exactly what I need right now thanks but it's just logged in right I can just click through yep awesome thanks and then here we go that's the that's the response for my lookup code yes it's a valid number it's okay no more it looks like this if you do the standard or advanced then you'll get more detail you can see which network they're on whether they're roaming whatever so that's adorable I travel quite a lot and the thing with the Wi-Fi is not that unusual however I know exactly how this API should behave and it really need the live platform available to me also my boss is getting tired of topping up my account because I'm always demoing something so I can use a mock server that reads our open API description and pretends to be the server we've described our fields requests responses we've described how that should look how to call it what you should get back so this is prism it's another stoplight tool when it starts up you feed it the file that you're interested in I'm that's a weird command because I'm running the bleeding edge because I'm testing something cool that they are making that it's not released yet first thing it does is output the endpoints that it understood from your spec so that can be a really good start like how are we doing oh you didn't get them all all right and then it begins a server so I've got this server running here I'm poor four zero one zero and if I copy that link I can just replace my base URL with that and in when I press send this time postman will just hit the local prison server and you can see immediately oh I got my sample responses this is all prison knows about it's only got what's in the server you can give it multiple one of examples in the spec so serve some different stuff and you can specify oh I'd like the error one this time it does a bunch of things but for this especially for library development especially the API is slow or expensive or annoying or you know not shipped yet then something like this helps enormous Li and it's something that I'm finding just incredibly valuable and if we go back to the console you can see a request came in this stuff happened this is what I responded so it's quite chatty and it's something that you can use in your own work to develop against an API that isn't there yet or that you can't call live or it's just too slow when you're on Airport Wi-Fi all of those things right so here all of the slides for the things that I've just said excellent and there's one thing that I'm not gonna do live is a little bit slow and fiddly and that is to generate an SDK you can actually generate the API end but I don't write that I'm doing more SDK engineering right now so and I think it's something that's more applicable to us as developers as consumers of api's and that's to generate the SDK and next mode we publish SDKs in I don't think I'm supposed to say seven different text axes thing I supposed to say six it's seven mmm and I think that API provider provided us DK's will always be the best option we have more than just API wrappers in our API in our SDKs and our client libraries they are we have some message signing stuff I mean yeah it's well documented you can build it yourself don't it's tedious some of the author stuff has a couple of different steps to it we wrap that up for you as a helper as well so I think that will always be the best option not every API provider can do this not every API provider has the tech stack that you need if they publish you the open API spec though you can make a good start by yourself so you can download that API descript and generate some rapper code that's gonna call all the end points of that API this one is the open API tools open API generator it has a docker container it's basically it generates some admittedly slightly hairy code but it works and a readme that says copy this code and put your config here so I copied this code and put this config here I asked if a PHP I'm not gonna ask for a show of hands but I know all of you have used PHP at one time or another mm-hmm and I got this I wrote line 9 and the rest came for free and this thing just works out of the box this is awesome for getting started like prototyping with an API that you don't know well and I think a lot of the value here is in having the autocomplete in your IDE being able to be like what are the endpoints I need that one now it's prompting me for parameters ok cool yes here is the country code here is the number I'm interested in boom it's ideal and the Finglas generated code libraries is very interesting also for companies who do publish SDKs I I'm not sure there's any real value in publishing something that is just the generated code except I guess you just generate it you can just install it with the dependency manager but I definitely would like to see more generated code with as kind of the model layer if you like this is also super valuable for and the strongly typed languages where you can just read off the spec how to do serialize the incoming JSON incredibly useful but then also with some user facing actual wrapper code that makes your API and the SDK that come in is it more delightful when things change in the spec because API is change it'll be great if we designed an API signed off shipped it and that was the end of the story my life doesn't work like that probably neither does yours and when things change then we can regenerate the generated paths and keep the separate user interface wrap apart all the value-add all the extra helpers and make it into one library but it makes it really easy to stay in sync with changes I've mentioned so many tools in this talk and it's it's a tiny fraction if you have a favorite tool even worse if you're a maintainer of a favorite tool I didn't mention it I'm really sorry and open API doc tools is the place to go to find out what the tools are for the thing that you want to do probably in the tech stack that you're interested in for the version of open API that you want spoiler if it's not version 3 then you can start with the conversion tools that will just update your spec for you then you're all good to go and we can all stop saying the word swag until the end of time and mmm there's a bunch of tools here so many I made I contributed this table of contents added thing because couldn't find anything it was in sections but there was no way to find the section that you needed I think I have been speaking on this topic for more than a year to a variety of audiences in that time the tools space has transformed beyond recognition we've gone from oh yeah we have one documentation tool that works really well and some rumors of other stuff that works for a small number of specs to this enormous list of incredible useful robust tools and they're all open source is an open standard we're building in the open we're learning sharing building upon each other integrating with the existing tools you know people build a validator they integrate with an existing Docs tool so you can render and preview your changes it's an exciting time and that means for anyone watching this on the video whatever I said is probably out date you should check this site and it's also again the site is open so there's a tool that's not here that either you create or that you know about then you just open them up or request they're good people and they'll review it and get it added so this is very much a community effort to try to keep it up to date there might be something that's marked as not having complete support if you know that it does you'll help us keep that information up to date because it's our go-to place for finding the tools that are available to us as a community and the things that we can do open API I think changes a lot of things I think it flips our understanding of where the changes starts lots and lots of organizations are still generating their open API spec from their code and that's a valid approach of course every scenario is different but I think the value in beginning with the spec being able to involve everybody from the very beginning to just prototype ideas changing a spec is cheap right I can do it anyone can do it it's the equivalent of an of an Excel spreadsheet right it's super accessible it doesn't cost anything to change its spec stage we haven't built anything yet but we can look at it we can try it out we can test it we can render the docs we can run them past people we can kidnap potential customers and ask them to give it a go right it's an incredible way to lead API change and I think that's what makes open API really well suited to our more long-lived applications I've been in web development long enough that at one time we built a website for a company in two years later they'd need a new website and we would do them a project and the website would be it would ship and then that would be it and then we would just replace it and our api's have looked a little bit like that too they don't have to and I don't think we build software like that today we build it intending to last intending to have a future intending to be maintained and have changes and grow over time by leading with the open API spec we ensure that we can we can keep everything we do in think so we have the spec we can generate the code stubs for the API we can generate the SDKs or parts of them perhaps we can have documentation up to date we can know that the responses the expected response from this API has changed maybe it has an extra field we can update all of our tests for our SDK libraries like there's so much we can do when we treat our API description as a first-class citizen where we make it the beginning of everything because everything can be connected to it so as one thing and it might be something super small we had an incorrect data type in our spec because they're all retrofit so there was a place where it was documented as an integer and actually it comes as a string and it was tripping up one of our strongly typed languages and it was like ha we were able to go back and fix that and get that same it wasn't causing a problem in the other tech stacks but it's now correct in all those places but it's very easy to propagate very easy to keep track of what's changed and I think that will make an enormous difference to the way that we are able to first of all consume api's right I'm a consumer first and to be able to just grab a spec and quickly explore an API that's magic I know you use it on anything I should know really well as well as such value there but also in the way that we publish API is the way that we run our API is really serious software projects not as things we bolted on the web server I think this is really key and I think you'll see more of it when you're in when you're researching api's look for the ones that have the spec for you to download grab it and see what you can do with it if you are an API publisher then could you describe your API how would that look what would you do with it the possibilities are endless I think it's a super exciting time to be working in this space I have a bunch of resources for you and hopefully my Twitter account will tweet that at some point and I've also really liked to just remind everyone who might be tired of the novelty of the app by now as we've been here a couple of days just drop in tell me what you liked and what you might change because I might give this talk again so that'd be really useful and yeah I've got some resources I'll leave them up on screen I'm really conscious that you probably all want to go to lunch so I will hang around for a bit take any questions you have but apart from that thanks very much

Channel: GOTO Conferences

Views: 77,028

Rating: 4.2191529 out of 5

Keywords: GOTO, GOTOcon, GOTO Conference, GOTO (Software Conference), Videos for Developers, Computer Science, Programming, GOTOcph, GOTO Copenhagen, Lorna Jane Mitchell, NexmoDev, Nexmo Developer, OAS, Open API, APIs, Developer Productiviy

Id: s9u3mXQZbXI

Length: 44min 55sec (2695 seconds)

Published: Fri May 08 2020

Reddit Comments

[u/goto-con]

Check out this 45 minute talk from GOTO Copenhagen 2019 by Lorna Jane Mitchell - Developer Advocate at Nexmo Developer. I've dropped the full talk abstract below:

Open API Specification is a machine and human readable way to describe APIs. From these specs we can generate documentation, create libraries, and ensure that our users know exactly what to expect from our APIs.

This talk shows you around OAS from the beginning, showing how to create the specs and recommending some tools to help the process. Once you have the spec, things get interesting and this talk will showcase some of the things that you can offer once your API is described in this way.

This session is recommended for writers looking to become more API-savvy and API engineers wanting to make their APIs more useful to their users.

What will the audience learn from this talk?
Attendees will learn about describing their APIs using OpenAPI specification, and what can be produced from the descriptions, such as documentation, tests, and even code.