 All right. Good morning. Welcome to this talk. I'm going to be talking about some work that I did over the summer on API client libraries. I want to be talking about, from a developer's perspective, how you're able to make a good one, how if you're a developer working on them, how to make a good one, and if you've already made a good one, you'll learn a bit about how to make it better. So, before I begin, I just want to establish that these are all basically the same things. So, I'm going to call it a client library. Around Wikipedia, you'll also hear a lot about library, but what it is, you know, software that makes it easier for developers to write. So, San Francisco just got muted. You're good. Okay. So what do people use these for? They're used for writing and running the box on the keys. So, automating tasks like welcoming new users or cleaning up vandalism or identifying vandalism or other tasks that are, you know, I mean, for a while, everyone's keeping the interrelated links, the inter-language links going. Aside from, so there's bot running, there's also using it to create data sets for doing research. So you can figure out that you want all the edits by people, by this specific set of users in this time, in this namespace, and get only the information that you want in an up-to-date manner. You can also use them to write scripts to do various quick maintenance tasks, and you can also use them as the data source for a number of people have for these neat projects that are somewhere like data visualizations and stuff like that. And everyone's a couple, you can follow up, but I'll put the slides up later. So, common features of these things. Basically, the idea is that you want to, I mean, computers are for doing the stuff that's obnoxious to do by hand. And API client libraries are no exception to that. So, if you have a library that will handle your HTTP requests, it'll handle cookies for you, it'll keep track of your session data. It can specifically make the medium of the API smooth and to use. It's not always the most intuitive, it's not always the most intuitive thing to use, and there are also things which are features, but which are just a little bit, can take a little bit of doing to handle yourself like query continuations and Seusser tokens. They can also have convenience methods for common API requests just so you don't have to type out all of the parameters for the requests like logging in or specific search or getting categories. And they don't always, but they can add a layer of abstraction on top of the API. The MediaWiki API in a lot of ways reflects the MediaWiki database structure, and that can be, especially if you're a developer who's new to the MediaWiki API, that can be a little bit challenging to deal with when you're getting started. So, if you don't want to think in terms of getting a revision or getting a text extract, you can just say, okay, get me the page contents and some client libraries will let you sort of think more on that. So, how are you going to get one? Well, you can go to the list of all of the, I think, most of the client libraries that are out there. But there's a lot of them, and there's not necessarily, for a lot of languages, there's not a whole lot of specific information on the particular library. So, that's a starting point in the sort of like, how do I find them? But when you're thinking about going to choose them, you want to think about those same things that are like, what makes any token? Well, it makes it easier or impossible for you to do what you need to do. So, yeah, you figure out what you need when you compare it to what's available, and that's really simple, right? It takes a little bit of research, and it means that you need to figure out what you need, and it means that you need to have some way to figure out what you might be able to expect. And that's where standards come in as a useful tool. When you have something that you can compare, you can sort of go down the list. Does it have these features that one might use? Okay, do I actually care about these things? Maybe not, but it's a tool to help you sort of figure out what you need and what you can, what you might want to think about if you're writing one of these. For most of the rest of the talking, we're going to take the perspective of talking about someone who's writing a client library, maybe a client library, but if you're looking for one to use in a project of your own, then you can just, not everything that I say is going to be applicable to you, of course, but you can take it as a certain point for things that you might want to be looking for. So as part of my working for this summer, I wrote this gold standard for what sort of, as media-wiki developers, we want to see from a media-wiki API client library. The general outline of this, and I'm going to go through each of these in some more detail and talk about the reasoning behind the points on the standard, is that it should be easy to install. You shouldn't have to share too many gags to get going with it. It should be easy to understand. It should be easy to look at the project page and say, okay, what can I even expect to get out of this? Is this sort of impacting framework? Is this something that just handles the HTTP and cookies and stuff for me? How heavy-weight is it? What am I going to get out of this? It should also be easy to use. So once you sit down and start writing codes, you don't want to have to go, oh, this feature turned out wasn't included even though I thought it was, or oh, I need to change these defaults so that I'm complying with the policies for the media-wiki API. And if there's sample code, then it's so much better. It should be easy to tell what's wrong, and as a part of this sort of shared ecosystem of open-source libraries and based on the open-source media-wiki, it should be easy to improve and to contribute and to get back if you find something that you can make it work better, and so you do. Alright, so I'll start with easy terms though. I'm sure there is someone in the world who really enjoys setting up developers environments, but I'm guessing that's not most of us. So as a library developer, and I should say, most of these things are small projects. They're volunteer-written, they're volunteer-maintained, and so I don't want to be like, oh, you all are not doing anything terrible. That's not the point of this, but the point is that if you want the library that you've written and you've shared to be something that other people can use and use easily, these are things that you might think about when you're trying to make it at least. So as far as setup goes, your goal is to make getting started as smooth as humanly possible so that developers don't have to put in a bunch of time and effort to figure out if the library is even going to work for them. So starting with what you can take is just right up what you've done to get it working on your own system. And for various languages, there's a lot of existing tools that can make it easier, package managers and such. So another thing that I found is that you want to make sure the installation instructions not only exist but are correct and easy to find. It sounds obvious, but it's an easy thing to overlook, it seems. So you can also package the library for installation through package managers. So if people are already using those tools, they'll be able to just get their library through that. And you can consider making it available through various Linux package managers. That's kind of if you want to, it can be nice. But the language app level package managers are a really good starting place here. Okay, so your developer can get started with this and can install it. So the next question is can I sit down and look at this and figure out if it's outwardable and how to use it to make the project work. So what's it capable of? What are its limitations? How does it work? And what sort of stuff is it designed for? Is it designed for pulling down data to get your data sets together? What research is it designed for? Which box is it? What's the purpose? And here you can approach this from a couple of angles. So first thing, follow general principles of good API design and I'll say more about that in a little bit. When you're writing a client library, you're writing an API on top of the API. So those principles are going to apply. If someone's looking at your code, they should be able to understand it. It should be readable, it should come into those applicable, and most importantly, it should be documented. Source code is not documentation, right? It can be a place to look, but ideally you have comprehensive and accurate and up-to-date and also easy to find documentation. For me, when I'm reading documentation, I find it easier to understand if I can get a snapshot of how to use the function in a larger scope and as well as visually. So sometimes it gets lost as to how something fits in context. So if you can get an overview first of how it fits in wider context and then you can tell them that's a lot more helpful than just being like, here's the stuff and here's the parameters. Oh, yes, definitely. So yeah, when you would want to do something, not just how to use it. Yeah, definitely. And then the easy to find. If you don't already know to look for it, finding GitHub Wiki is not the UI there is not the most intuitive. So if that's where you have your docs, put a link in the read me or something like that just so that people actually know. You don't have to define the tab on the site and click that. So talking about those API design principles, the biggest one is that you want to be very deliberate about what layer of abstraction you're working on. So if you're writing functions to handle the API call in general so it's parsed the response that comes back. You want to separate those as much as possible so that people, so that developers who are using your library know where to look and have the appropriate signposts for what to use how. You also want to avoid redundancy. If you have a couple of methods that are doing the same, basically the same thing but are something different, make sure that you need all of them and highlight those differences. Don't make the developer who's using this guess. Naming is considered one of the biggest problems in computer science and that's for reasons. So for the API, names should be descriptive and they should relate to the level of abstraction that they're working on so that the developer can look at the list and make a good guess at where they want to start. And again, use your languages, idioms and conventions and all of this boils down to don't surprise your users. So that's the sort of making it easy to wrap your head around and get started. When you're writing code you want it easy to use and this sort of leads into easy to understand because you need one to do the other. But you want to make it easier to use your library than not to use it. So the benefits need to outweigh the frustrations. So that means that you want to make it clear what features your library offers. You want to, you know, clearly if it's a client library, you want it to offer access to one or more of the APIs. So media-wiki, but also if it can handle wiki data, that's somewhat different at the eye, but it's also useful. It should again offer documentation that's not source coded. It should offer the sample code. And on sample code, if you offer it, it's going to be used because programmers like to take the resources that are offered and not do more work than they have to. And when we're talking about good here, what I mean is efficient and courteous and secure. So if you can make your underlying library code efficient in terms of API calls, that's work fits. That's going to allow your developers to do that. If you have your library defaults lined up with what's expected for media-wiki API clients, then that changes that your developers don't have to make. And if you're using HTTPS for your requests, by default then that's again a choice that developers who are writing the API clients don't have to make. So here are just some of our luck with the easy to understand, but these are things that you want to consider if you're writing or maintaining one of these libraries. Okay, and everyone's favorites in debugging. Programs and native code, code has bugs, more code, more bugs. And this is just one of those facts of life. So given this, how can we reduce developer frustration in finding these things and make it as easy as possible to track down the difference between what you expect and what you find? So first, you can make the expected behavior clear. If there's a... If you have a function that has a side effect, make that clear. Don't make that a surprise. Make the bugs of the library easy to find and make it easy for developers to find what they're actually expecting from the underlying media API. So to do that, a couple of things you can do. You can include unit tests for at least the longest and most frequently modified functions in the library. So that means that if you're changing up your library code then you can tell if you've broken something or if this is just something that your users are doing themselves. How do you test that? Do you directly run it against the media API or do you have more code? I think it depends on what we're trying to test exactly. I've seen both approaches. So are you aware of the library that uses the mark? I'm trying to... The one that I spent the most time looking at the test site was Java, which is that framework. And if I'm remembering correctly, there were so much that some of it was just a test if you can get to the API and then the rest of the tests. Okay, cool. And if you're getting really clever then it's polite to just comment and say, okay, I know this is hacky, but this is the corner case I'm addressing or sort of just if you're doing something unexpected then they can edit that. And you can also just to make it easier to make it easier for developers to sort out the letters. You can link to the relevant section of the API docs for methods when that's applicable. Okay, so you have this library. We're using it. People are maybe sending in some feedback. You want to make it easy to improve. So what are things that make it hard to improve? When contributions are... All right, go ahead. Like someone sends in a full request and it just sits there for months. When projects look dead, so either... So there's no note. It looks like it might be updated sometimes, but there hasn't been anything for the last... for the last number of breaking changes to the API and it's sort of unclear what the status is. If someone's looking to contribute but there's no really obvious starting points, that can be a sort of like, well, maybe I could do this and maybe I could do something else. And there's... I haven't run into this on any of these libraries, which is awesome, you know, this is the end of the facility in this respect. There are also areas to people wanting to engage. So we lost audio for San Francisco again. Sorry. All right, this is... It's good now. Okay. So you can respond to contributions and see that even if it's... You can respond to contributions and feedback, even if it's just to like, hey, thank you. Thank you for the web reporter. Sorry, this isn't currently maintained, but I'm glad that it's been useful for you or something like that. If there's someone who's new to the project and you need to write in API clients, you can have a sort of like, welcome your developer section in your doc somewhere. One of the most important things I've found for encouraging new contributors is to document your development practices, not just your code. And if you're doing that, you can also sort of... If you have bugs or issues that you think, okay, yeah, this wouldn't be that big a deal, but I don't have... I'm not going to deal with it anytime soon. You can mark that as maybe something that a new contributor might want to take on. So I think the biggest thing here is to set accurate expectations. I mean, people are busy. Library maintainers are busy. Developers are busy. So if your library is unmaintained, say so. If it's accepting requests and keeping up with breaking changes, but there's no new development, say so. If it's underactive development, that's cool. Say so. Beyond being good as yourself, you can also set expectations for respectful behavior in project-related spaces. If you're maintaining it, you can, like I said, respond. One other thing is that you can note compatibility with media and key versions. So it's not that you write one of these and you're obligated to keep it up to date, but it is helpful for people who might want to use it to say, okay, this works up to version 19 and that's it. So just giving people the information that they need to decide to make the decisions about what tools they want to use is the most important thing here. You want to respect your own time and you also want to respect other people's time. And just for the sort of legalities, if you actually release it under a free license, no one has to worry about there not actually being a license to say what they can and can't do with it. So in general, there's code-related ways for usability and there's ways that aren't strictly code-related. So to keep up to date with API design, keeping those levels of abstraction in mind, testing appropriate to what you want to be doing. Use tools that are available for you. So to keep up to date, you can use automatic tools that pull the documentation out of the comments. You can use package managers, et cetera. And you can have good defaults and good examples in the code that you wrote. Things that are not code as such is make your intentions clear, communicate clearly, make those examples clear and usable, and have documentation and have it accessible and readable and with context, what you're using, how you would use it, the rest of that. And pretty much all of this comes down to respect and empathy. If you've written one of these, you're a developer and that gives you some idea for what other people might be looking for. I'm not going to spend too much time on resources. These are mostly for people who want to follow up with the slides. There's the client code page. There's evaluations for about 12... so far there's evaluations for about 12 libraries compared to that gold standard. If you want to improve, if you want to add to those, then please do. Larger library projects might have a list or IRC, there might be presentations or how to use them, developerexperience.org has a lot of good links on thinking about developer experience because developers are people too, just like software users are. You can also look up documentation tools for your language. General API resources, really great place to help get your head around how it works and what the options are. Various documentation. Dev.wikimedia.org is in progress, but when it's up, it'll be a starting point for you to engage with development using the API and similar, and there's the mailing list. So, yeah, just a couple of quick ways to get involved. If you do use one of these API client libraries, you can help evaluate these especially the PHP ones. After I finished the work I was doing this summer, I had a couple of inquiries about whether I was planning to do any for the many available in PHP and unfortunately that's not something that I'm working on, but if it's something that you are, that's good. Offer feedback and you can contribute to more documentation. I do want to acknowledge a handful of people. I was doing this work as part of my internships through the free open source software outreach program. My mentors for Simona, Harry, Karisra, and Salah Fahin and Redrush and Roland and Dean were giving me a lot of helpful advice as I was working on the project and Kijil helped run the project and make sure that everything went smoothly. So thank you very much, and if you have any questions I will ask them. Is there anything for me? If you're going to hang out, you can ask any questions you have directly. Max, if you have anything, can you go ahead? As an API developer, I can just add a couple of words. We are doing a lot of deprecations in the API, so we recommend you to use libraries that use the JSON format and if you're developing a library that relies on something else we recommend you to think about migrating to JSON and another thing libraries should set the user agent clearly sorry so that if something goes wrong, people will be able to see from your user agent that it's a bot and ideally whose bot this is. And if you can include a method to generate a user agent given the contact information and similar that's even better. Ideal client library sets its own user agent header and allows you to add the client information to it. That's it from my point of view. Anything else? So I was just looking through that API client code page on Meta and I didn't see a summary of the ratings that you gave. Is there a table with a row per client library that we can reference? The information right now is just in the individual evaluations page but that's a good idea to have something that people can look at at a glance and figure out if it meets the basic things they need. As an API client developer I really love to get a quick overview and updates on what's being deprecated and what sort of standard practices are. Right now I know that there's sort of a transition about query continuation but I have no idea if that already happened, when it's going to happen. How should I best keep up on this? You should subscribe to the MediaWiki API mailing list. I'm on that mailing list but there's just too many. There's often discussions about what really affects me as an API client code developer. Subscribe to the MediaWiki API mailing list. Okay, there's a separate one. Cool, thanks. Alright, I think that's it. Thanks so much for coming. Sue, I'm going to add some links on IRC. Thank you all so much. Thank you.