 Okay, so welcome to my talk. My name is Honza, and I write open source for APRI, which was acquired by Oracle last year. So those are the new masters, and I'm sort of a hobby cartoonist as you can see, and I write software in two programming languages, mostly in JavaScript and in Python. While JavaScript is my day job, Python is something I do with love, and I'm actually also sort of Python activist in back in the Czech Republic. I help to grow the local community and so on. When talking about this, I have to tell you a little advertisement here. I'm part of the organizers team of the Baikon.cz, and I invite you to submit talks and workshops to just open call for papers. It is amazing conference. It has everything conference needs to have, like talks, workshops, people playing ukulele, people having a good time between highway and railway, people partying, and people making people pyramids after partying. It is in Prague, which has a lot of medieval houses, nothing against Brussels, and it is in the Czech Republic. I've seen a theme here on Fosdam, and in Brussels and in Belgium, that beer is the thing here, and I want to assure you the Czech Republic takes beer very seriously. So this is Baikon.cz, and this is end of my little advertisement. Now let's get to the talk. Serious stuff. So API. You probably came here to learn about testing your API, and I want you to understand why should you do that? Like, what is the why? Because how is easy to Google out, but nobody tells you the why. So API, it is application programming interface, and the interface word is the most important here. We have interface of libraries. As a Python developer, I can write my Python program, I can install Django, which is a web framework, and then I can use its interface to leverage whatever Django offers to me. Then the internet came and we started to talk about interface of systems, so I can curl the GitHub API, and through the GitHub interface, like the HTTP interface, I can do whatever I need with GitHub, I can get information from GitHub. And this all seems quite technical, like computers stalking each other and programs stalking each other, but it's not. Because as I said previously, I need to get some information from GitHub. I need to use whatever Django offers, so it is something between computer and the user. So every interface is user interface, even the web API or the interface of the Django library. And as a user interface, it should be treated as such. You may not see the code properly, but just imagine, this is a simple HTTP request made by a standard Python library. So when you want to do a simple HTTP request, you need to write, I don't know, 10 lines of this crazy code just because you wanted to pass user and password except of just requesting a simple URL. Do you like this code? I mean, it doesn't matter if you like Python or not. It is long, it is not very readable, writeable, maintainable. It's basically, with single word, it's ugly. Then a person called Kenneth Rays came and realized this can't be like this anymore and wrote a library called requests. And the claim of this library is it's HTTP for humans. So with the request library, it looks like this. And please note that just the first line is usage of the library. The rest is just inspecting the response. So we basically got a one-liner, which is readable, which is writeable, maintainable. It's beautiful. And as you can see, the differences between interfaces are very user-oriented. Because the machine, in this case, and in this case, the computer gets basically the same instructions, the machine doesn't care. It's perfectly fine with both, but the user cares. So how do you design the interface in a way that is appealing also to users? You need to position yourself into basically into a role of your future user. In that case, you should have enough empathy to design something which actually makes sense and is usable and so on. Because otherwise, you just, as the author of the library or of the web API, you just write a couple of functions into a file and call the file a library and if user complains, you just say, deal with it, it worked for me. How do you do that? How do you position yourself as your user? Well, the easiest way is to write test. Because in test, I'm easily positioned as the first user of the library. Here I need to use the library to actually write the actual test to call it, to inspect whatever it returns. But it needs to be test first because I need to think first before the actual coding. So I need to think about the interface. I need to write the test first. I need to write the library, write the code which uses the library before the library exists. So this is TDD, test-driven development. I write the test first and this helps to design the interface. I pretend that the library exists, I write a test, I test it, it fails because the library doesn't exist and then I implement until the test is green. What can I do else? I can write down the behavior first. I don't know how many of you know Gerkin or Cucumber or are familiar with it. It's quite a lot, good. So imagine there are text files like this. It's simple text file but it's structured and you write down behavior of your program into this file. The benefit of this is you focus on the behavior of the program from a user perspective and you can write this before the implementation actually exists and because it's just human readable file and it's versionable and so on, you can put it on GitHub, you can share it with whoever you want like your colleagues or with your customer. So you can easily agree on the behavior of the program and then you have it coded in these text files. And the benefit of this is that you can test it. It is sparsible and you can write tests which test the behavior written in the files. This is really amazing because you think about the behavior, you write it down, you agree with people on the behavior and then you write the implementation. But who says the implementation is according to the behavior? Well, you can never be sure but with the tests, you can automate that you can be always sure that the implementation fits the original description. Is important part, the most important part. So you design the thing, you set up the tests and then you implement and you're implementing and implementing until the implementation actually fits the original design. So you think, agree, you promise something to your users, to your customer, then you set up the tests and you test and you fulfill the promise. But back to Kenneth Rates who made the request library. How did he design the request library? What approach did he use? He wrote an article which makes this question easier. How I developed things and why? And in this article he says, before I start writing a single line of code, I write the read me and fill it with usage examples. I pretend that the module I want to build is already written and available and I write some code with it. And this approach is called read me driven development. Tom Preston Werner wrote article about this in 2010 and the thing goes like this. You have simple read me file and it contains couple sentences or whatever the library does and usage examples. And those are like crucial, the essential usage examples, like the most important stuff so the user actually understands how the library works. And the benefits are you have chance to think through the project first. It's very important, it helps to design the interface. And you don't have to go and write the docs when you are done with your project because at the time the docs already exist and as with the QCAM brand and so on, you can use the interface before it exists. You can show it to your colleagues and they can actually write code which uses the library because they know the interface, right? Or they can tell you, oh well, this parameter, I don't know, I don't like it and you can change it before you actually start to write code. And in the read me, you put the essential interface user expects. That means whatever is in read me, when it's broken, your library is broken. If it's not in read me, it's a bug, it can go to issues and so on. But when it's in read me, your whole library is broken because user comes to read me, copy pastes the example, puts it into terminal and if it doesn't work, then library is broken and it's going to look for a different library. So it's essential interface. It's essential contract with your users. But again, yeah, and this must not get out of sync with code. But how do we achieve this? Again, like we have some promise and we have implementation. We test it. In Python, we have doc test. Which actually takes the text file and is able to parse out the examples and run them. And if they don't have the output as you document it into read me, then it fails. You can put it into continuous integration and you can ensure forever rest of your life that this read me will be in sync with your code. So you think about the interface, you agree with everyone on the interface, you write it down as a read me, then you set up the tests and then you code until the implementation fits the promise. And what if we could design and test web APIs like this? Imagine you have a read me with a name API because it's not read me, it's API. And it has just a couple of sentences of how the API works and you document a request and response with examples. Would it work? Well, it works. This format exists. It's called API Blueprint and it's marked down based. It's basically free form text with some structure and it has some users. And it's human-writeable, human-readable. It works as read me would work, but at the same time it's machine-readable. So you can parse it and you can do whatever you want with the data you parse out of this document. And there is a tool which I'm working on which is called Dread and it works exactly as the doc tests. It takes the document, parses out the examples, runs the examples against your implementation of the API and tells you whether it fits the API description or not. It has documentation and a nice logo. I have a couple of stickers and it has some users and I'm very proud to say that it's finally JavaScript because we, a couple of years and years ago, we wrote it as coffee script and it's like two days ago or something like that. My colleague became the biggest contributor of this repo because he switched the whole code base to JavaScript. So finally it's JavaScript and there are some blog posts and so on. So you're basically not the first one to use it and there are people talking about it on conferences. And sometimes because web APIs can be a complex thing, you can have authorization there or something, you may want to extend the testing with so-called hooks and you can write hooks already in these languages. Most of them are contributed so actually if you don't see your favorite language, you can easily set up your own hooks in your own favorite language. And you can put it into continuous integration and forever, the rest of your lives, you can ensure that your API will work as you designed, as you promised. And moreover, you can make the document you wrote, you can make it something central to your API development. You can, as it's machine readable, you can parse it, you can generate documentation out from it. You can generate Moxserver out from it. Moxserver is something which just replies with the examples and you can give it to, I don't know, your mobile developers prior to actually implementation of the API started and they can try out the API and they can give you feedback, like no, no, no, this parameter, it doesn't work. And you didn't write a single line of code and you have feedback on your API, like real world feedback. And you have the tests. So basically the document becomes a single source of truth about your API. And if I add logos here, this is the API blueprint, it's marked and based, this is what we do in API and this is what I do in API. And you may ask, what about the open API spec? Formerly known as Swagger. It works the same way. Instead of API blueprint, you use the Swagger spec. But it's YAML based or JSON based and I don't think it really, really fates the design first or document first scenario, but up to. So again, we have these one, two, three. You think, you agree about your API, you write it down API description, you set up the tests with red and you fulfill the promise once you implement the API. You can be sure that you implement the promise. This, like testing the implementation against design allows you designing before implementing because otherwise you couldn't be sure that it's not out of sync. Designing before implementing allows you better design because when you design first, you have better design. Dread allows you better design. So remember, do everything first except of coding. You do coding last. Discuss the interface design before implementing. Use the interface before implementing. And use the interface design as a single source of truth. Test the implementation against design. This is the most important thing. Whatever you do, test the implementation against design. NPS, your APIs use the interface. Don't forget about that. And that's one question and then the rest of the hallway. Anyone have one burning question? How do you formulate the tests as well? They will make the other and you will get the problem. I only have the formal syntax, but no semantics. The testing of the API works basically on base that you have the API description file and it's a specification by example. It's similar to Cucumber or the Readme that you need to provide the examples. The examples. Yeah. You need to provide the examples. They're crucial because then.