 can attract friends, make you rich, and change the world. So depending on who you are, you might be thinking this sounds kind of interesting to APIs or interesting. Others of you might be thinking this sounds absolutely boring, what could be more boring than an API. So if you're in the latter camp, I apologize in advance for the next 40 minutes. But I do want to try to convince you that APIs are interesting for a lot of reasons. I'll only just spend a couple minutes a day on the basics of what an API is and how to work and all that. And then I kind of want to get into some things. So I'll try to do this in like two minutes. I have a timer right here to self-tell me how I do. So an API is an application programming interface. It's a way for two applications to talk to each other, two bits of software to talk to each other. Kind of like a user interface where a user talks to software. An API is a way for software to talk to software. So the first interesting thing is that they're both interfaces. There's a couple kinds of APIs you can call them. You can call a library or an SDK an API. It's kind of like a local API. It's like an API within a specific system of software, maybe within the same memory space between two bits of code. So NetSAPage and Ruby is like an API to Ruby functionality. What I'm going to talk about today is not this type of API, it's web service APIs. A web service API is a way for two kind of external systems to talk to each other. You can think of it like a universal API. You don't have to be writing the same language or the same operating system or be located in the same server or facility or anything. Web services, early web services were done with the simple object access protocol, SOAP, which was named simple, I think with a straight face, which is interesting. SOAP has given way recently to REST as an API. So I'm not going to talk too much about it. So REST is a great way to run an API and it's basically how almost every API is written today. REST is just the realization that HTTP is an API protocol. In fact, the web is an API. It's an API between two bits of software, your web browser and a website. So your web browser makes an API request like get records, I want to read information, or like post a record, I want to write information. So finally, when you're doing an API, you need some data structure to send information forth. Typically, that is either XML or JSON. XML is kind of a trench, a lot of places. JSON basically does the same thing in a much more elegant way, but you may have to worry about both. So actually, it's exactly two minutes. So I did okay at that time. I practiced this a little long. So there's the two-minute intro to APIs. Let's talk about things that are a little interesting now. And I want to start autobiographically and talk about my experience with APIs and give-ins to you, some other things. So I'm a co-founder of a startup called ZenToder. We are basically an API to a high-performance video encoding farm in the cloud. So our whole product is an API. We don't really have a product, we just have API. We have a user interface, but our user interface is not that interesting. You wouldn't pay us money for access to our user interface. Similarly, we have stuff going on in the background, but that's a black box. You don't know how we do what we do. All you know is whether or not we respond properly to the API requests. Has anyone here tried ZenToder before? So as far as you guys know, we just have a guidebook in the office downloading files when they come in, encoding them with Handbrake, right? But you don't really care as long as we meet the obligations of our API. We don't actually, but we could if we had enough people. So let's kind of look at some categories of APIs. Is this cutting out like, can you guys hear me okay? Yes. Let's try the other mic. Let's try the other mic. Is this better? Can you hear me? Yes. Good, all right. So let's look at some different categories of APIs that you might see. The first category is what I want to call like secondary APIs. These are things where the application works without the API. The API just sort of extends the functionality of the application. So you can use Flickr on its own, right? You probably, that's how most of us probably use it. But it's interesting, you know, interesting move Flickr kind of opened up all that functionality to via API which lets you do more and more powerful things with it. So you can use Flickr without it, but the API just sort of extends the functionality. Second group of APIs that came along recently is infrastructure as API. This is where I think things get really interesting. So Amazon Web Service is like API to Linux or an API to file storage or an API to message you and et cetera, et cetera, that's pretty cool. The next group is really sort of a recent trend in software today. And that's APIs to specific technology. So things that you could do without an API, you could buy a box, you could buy a server, you could buy some software to get all this functionality. We can all do it ourselves, but it would probably take us a few months or whatever, we'd have to maintain it. Have some capital expenditure. So Twilio is the API to telephony. You can, with Twilio, get like pays-to-go like telephone lines. That's pretty cool. You could do that on your own with Asterisk or with like a big PBX box or whatever, but the fact that it's delivered via API is powerful. The last group of APIs is, I didn't know what it's called, so I called it like sci-fi APIs. These are things that are kind of crazy. This is an API cloud. Pipe cloud is like an API, or it's like Python processing in the cloud. You include Python in your Python application and execute it, and Python is actually executed in the cloud. So if you have some massively paralyzable problems, you can write your code locally, run it locally, and it actually gets run in the cloud, which is cool. Amazon Mechanical Turk and Crabflotter are an API to people, which really sounds like it. That sounds like a Philip T. K. McStory or something, right? So that's kind of where APIs are right now, so some categories of APIs that are kind of emerging. What I want to spend most of my time with Foxface is talking about how to make an API that's good. We spend a lot of time on our API exemplator, on the design of it, and how we do it, and we get people praising our API, people who like our API. But I don't want to shill Zenfutter too much in this talk, so I'm actually going to redact Zenfutter whenever I use it, so there you go. So if you hear some things, what do you guys think? Hacking up integration with redacted and recurly. I really love good APIs. They make my life as a developer suck so much less. Does anyone resonate with that sentiment? That APIs are absolutely painful and horrible to work with. The whole point of APIs is to give you some functionality in an easy, quick way. So it's important to design these things well. But how do you, in fact, design a good API? Who else has worked on an API before? Good, that's like a third of the room, that's cool. Probably a large part of the recipe will at some point in the next few years. So we're going to look at like 10, I don't know, 10, 12 tips from our experience of how to build a good API. We actually don't do all these, but we should be doing it. And then maybe we can talk if you guys have ideas of other things that contribute to your API design. So first, you should version your API. And if you version your API, you should do it early in the life of the API. It's kind of hard to retroactively add version depending on how you do it. The reason you want to version an API is this. Let's see an API that lets you read a record. So this record, the color is green, the velocity is a little bit. What if you want to change that instead of returning green as a string to returning green as a hex value? You want to do that instead? Well, what's going to happen is that ever it is depending on your code to behave that way, their applications are going to start breaking. They're going to get unexpected behavior because they thought green was a string instead of a hex value. So what you do is you version your API. You put, there's a number of ways you can do this. This is just one example. API slash review one, and then the action. And then if you request this action with this, you get the string green. If you request v2, you get the hex value. A side note here is you shouldn't do this too often. You shouldn't have version after version. Whatever possible, you should try to avoid breaking anything backward from the penalty. This is kind of a pain to manage multiple versions, both for the users of the API and the team. Second, you should follow REST conventions. REST is basically the way every API is written. I'm sure there's exceptions, but it's a great, simple API language. Everyone's using it, and everyone's using it already on the web, even if they're not building APIs. Has anyone here built a Rails app before? If you have, you have built a REST API. So there you go. The Rails controller start doesn't even have to really change for you to actually make an API specific app. Exactly what happens by default in a Rails controller almost exactly is what you need for the API. So that means combining verbs and objects. Whenever you do an action, you end up cutting a verb, something that's done, and something that's done on a team. And that's why REST is sort of an elegant way to define the APIs. It's kind of the way we think, right? You read information, you write information, or you delete information, and that information or functionality can be record or a job or a message, or whatever your application is concerned with. Next, use good HTTP codes. Here's some of the codes that we use in ZenCoder. You probably see 200 and 404 before, but there's actually a lot of different HTTP responsibilities. Actually, we don't use for HTML if you hot. We'd like to at some point, so. So if a user's posting data for creating records, you could respond with a 200, okay, as in we acknowledge your request successfully, but you give the user more information if you respond with a 201 created. You actually tell them that something was created. 400s are client errors, 500s are servers, you guys all know this. We use a 400 data request for a now 400 request, like in now JSON, we call it a 400. 401 unauthorized is obvious, so we're trying to do something where you don't have permission to do you. Paper requiring, we don't use that now, but we may at some point, if someone tries to do something they don't have, they're not set up to properly pay for that, if it's paid action, 4.22 unprocessable for something that doesn't validate maybe. You see a lot of these in Rails, but there's many more response codes, and you might have other ones that are more applicable to your application. Next, use smart validations. Let's say someone posts this data to your application. API key of not a real key, and assume for the sake of argument that it's not a real key. How should you respond? You do like a 500 server, it's the wrong key, so you blow up, but that's the wrong code, because that says that it's your fault on the server side, not their fault. So it's better than that, you do a 401 unauthorized. But you can actually go a step further than that, you can actually give them some information, because that might mean that they try to access with a valid API key, a resource that they don't have permission to. So you can send them back errors. Anyone ever seen of an array of error strings before? This is exactly what you do with a web form in Rails, you do the exact same thing in API. If you want to show them this, not just say that the API key is not found, we can validate the structure of the API key, and say that it may not contain spaces. And we can go one step further, and not just say that it's not found, but tell them how to find it. Please log in to example.com slash account slash API to retrieve your API key. Guaranteed that you use our scene this message when they're struggling to integrate through that, is gonna be very glad that you put it there. Another example, what's wrong with this JSON here? Listen, call.com. I think that's something that I've probably done 30 times in the last couple of years. So when this happens, you can return a 400-bound request, but why not actually make a JSON parser into your API, and return what's wrong with the request? So error is JSON is not valid, and it provides a syntax error. There's libraries that do this that you can get on GitHub. Next, if you want to support everyone, consider supporting both JSON and XML. Reason being that this guy with the servers and the nice shirt probably doesn't know what JSON is. It may be just like a security error. Whereas this guy is not gonna use XML on Chris. You can use it, it's really easy to support both. You can more or less translate between JSON and XML back and forth, and Rails also helps you out with that. So if you submit a request, and you specify content type of application JSON or content type of application XML, Rails will actually automatically parse that JSON or XML into the branch cache, just like you're posting a web form. Also, I'm a little slow on the Rails 3 update. So this is Rails 2.3, and I apologize for that. Is it different in Rails 3? So this next one I think is different. Same principle applies. So Rails will automatically handle that in-bound, and it obviously also handles it on the response site. This is different in Rails 2, right? You can still do that. There's just a better way, maybe. So it's not that hard. The biggest problem is that arrays are kind of hard to define in XML than in JSON, it's a little less elegant than Rails.2.xml, where .2.xml doesn't do it. That's sort of the way you want it to work. Anyway, next, you should document your API. Integrating with the API that is not working or worse is incorrectly documented, is basically impossible. So put a lot of time into this. This is not the most fun part of the project, but it's really important. It's also something that users really appreciate as well. So we actually, to do this, we actually wrote a DSL for our document API. And we also, in the comments, because we have a lot of settings for our API, we have like a hundred settings, or I don't know, a hundred-secretary API, but we wrote this little DSL where you can take a setting. So this is the audio channel setting. You can specify how many audio channels you want when you encode a video. We have a short description, a long description of examples, valid data types, et cetera. And then we can convert that into sort of like nice dynamic documentation so you can see all this information, actually see like a JSON example of what it looks like to use this example, or the setting in the API request. See an XML? That says XML right there. I don't think you can see that. Switch to XML, et cetera. This is, we're like open sourcing this to, so it's a little raw. I think it's something that could be useful in other places, so. Next, real simple one. Even if you have a really easy, nicely-designed API, it's nice to have like libraries for it, have like a ruby wrapper around your API, have a Python, a PhD wrapper, et cetera. Definitely have a raw API as well. So that user, closure users, if ever cannot use it without using one of these. Support your API, especially if it's like a major part of what you're doing. If it's like high-reviewing your library. Because at the end of the day, APIs are kind of scary. An API is basically a black box to use something that's probably critical to you. And you have no way of troubleshooting or debugging or figuring out what's wrong if the API doesn't work. And if it's unsupported, it's kind of a dangerous place to be. And if it is supported, again, it goes a long way towards what's making APIs awesome. I'm gonna go through a couple of these just in a little bit of time, but I think your API is fast. If you have a request, don't necessarily have to have it all over the head that a normal web request has. So consider using a different, using middleware for your APIs or maybe something different on the back end. It's much easier to write code that hits the API like 1,000 times a second than for a user to click a browser, like reload 1,000 times a second. So you will give more people accidentally killing your API. So making it fast helps there. The other thing that helps is rate loading. You might want to consider not letting a user make more than a certain number of requests per second. Are you stupid? At least for things that are not that needle, e-mikers, etc., and all that. Couple more. Consider logging API requests. So every time a request comes in, write it to some sort of data storage, temporary, or something like that. So you could like, and then take that actually display it to the user. So the user can like log in and take a look at all of the APIs that they made. This is really useful when they are trying to get set up with the API and trying to figure out maybe why something didn't work. Give them the ability to do it and see what they sent to you, what you responded with, and if it's a problem, what's wrong with it. Last thing, even though an API is ultimately for software use and not for user's use, you can build all sorts of great tools around an API to make it easier for users to understand the API and to get set up with the API. We have this little thing called an API request builder that we built. It's not a huge piece of software, but it basically lets a user kind of interact with their API and get an example of what the JSON that they need to post to us is. So you can choose your settings and basically copy and paste that right there and that's about an API request. When this is submitted, you'll see the response that we give you back. So you can basically build your application and at least start building up on this. So what else? What are some other ideas for what makes it an API? Different authentication management. Say it again. Different authentication management. Great, different authentication such as. Basic authentication over HTTPS. Still works. Yep, yep. The ability to generate new access keys. New, sorry. Access keys? The ability to generate new access keys. Yeah, definitely, yep. Another simple web tool you can make an easy way for someone to change that if their keys compromise their loss or whatever. Good names. You see it, you go, you immediately know what that is. Yep, good naming of the fields in the API. Even the big of the controllers and actions in the API as well. Yeah, it's just like variables. We're Ruby programmers. We don't call our variables like S or like, you know, we name our variables things that you can read and you know what it is. Same thing applies here. Client library wrappers around your APIs. Yeah, client library wrappers around your APIs. Consistent responses. Consistent responses. Consistency in general. Well what sort of consistency? Similar methods behave similarly. Similar methods should behave in the same fashion. Sure, yep, similar methods should behave Similarly. Similar test framework, sandbox environment or even unit test kind of gen library would be great. Yeah, that's great. A sandbox, people should be able to do anything with an API without killing your system. Good examples. Good examples, yep. Guestable URLs. Guestable URLs. In what sense, and in what way? That if there are products, there should probably be a product URL on it. I don't have to read some documentation to figure that out. Sure, yep. Or if a person, slash ID, slash friends, I should be able to figure it out without reading some documentation. Yep, good. One thing I think is really cool about it is with the Twitter search API, I don't know if it's still this way, I don't know if it changed it. You can go to search.twitter.com and search and the same thing you search for there is what you get when you pull the Twitter search API. That's kind of cool, right? It's like a way of interacting with the API without actually using the API. So you have flexible building, reporting, security structures. Flexible building, reporting security. But consuming your only job in some steps so that you know in terms of the view of the customers in the workforce. Yeah, definitely. Consuming your own API, being your own API customer, definitely. Yep. Why search, I don't know. Well, the same thing, consuming its status so people know we're down to be very useful. Yeah, good status, absolutely. And not just status of whether it's working or not but issues that exist around the API. When an API breaks, conceivably thousands of other applications are waiting at the same time. So those kind of things are really important. Cashability. Cashability. Responses should amongst other things is like, e-tiles if you can manage stuff as you want. How long you live, that kind of thing. So that as a consumer I can tell what I mean by the question. Yeah, that's great. So you're using e-tiles at some time to lose all that amount of data you send back. Data integrity. Data integrity. Yeah. Live, same as before. Like, you want your data to be there. You don't just want your data to just go away. If you're running right now. Or you think you have like flicker losing, like you can use just accountants. Yeah, just things that are like bad things. Yeah. I don't want to do that. Single responsibility. Same work. Yeah, that's good. So some level of like animosity. Like, you should let people be able to like, change the enterprise or choose just one little piece and combine them in the way that they want to find it. As opposed to you forcing, you know, everything into a single structure. Batching requests. Same work. So five operations that I want to call from, I agree with a mobile request. I can't say mobile and with five requests. You all can stop from that. Interesting. So the ability to combine multiple requests in a way that the server will understand that it's actually multiple. Take one request and do five actions. Right. Yeah, interesting. Like a support forum or IRC channels or both? Yeah, good. Support forum, IRC channel. We use campfires, same as IRC, but kind of on the web, which is really convenient for users. But if you're doing a hacker project, you're seeing absolutely different support form, especially if you want users to support each other. Well, what's the end result of this? What happens if you create an awesome API? What do you get out of it? I kind of alluded to three things in the title of my talk. Right. PC funding. You get PC funding. Yeah. Okay. There you go. Okay. Yeah, so three things. Can make friends, get rich, maybe with, or without these, although PC funding doesn't really get rich, but it makes them rich if you can see. Or third, not change the world. So, let's talk about this a little bit. An awesome API can help you make friends. Here's a tweet we saw a little while ago. Redacted is so awesome that I'd like if you offer their developers free hugs. That's like an offer for free hugs from a total stranger. That's interesting. I think there's a reason for this, a reason why this happened. I said, awesome this gets noticed in some places more than others. There's probably some economic term for this, or like psychology term for this. I'm gonna call it an asymmetrical reward curve. This is how it's kind of fancy, I think it expresses this. Some things in life as quality, give us up, the value goes up, linear, let's say. There's other things where his quality goes up, then the value doesn't go up quite as fast. He's less, I don't know, a larger value as his quality increases. There's other things that follow the opposite pattern. When you start to get better and better, it's more of a value. Let's look at an example, bus driver. The best possible bus driver. How much better is the best possible bus driver than the bus driver? I'm just talking about only with respect to driving buses, not like a bus driver who fights crime or something. How much better is the best possible bus driver? Conversely, the worst possible bus driver is a pretty big concern. Looking at the opposite, I think sports is a great example of the opposite curve. The best possible basketball player is not like 10% better than the guy at the line. They're compensated according to people. Same is true in art, in entertainment. And I think API design follows this sort of same pattern. And I actually think a lot of developer things to you, but let's stick with API design. As you increase the quality of your API, it gets more and more noticed and valued and appreciated. One more email, and I'm not gonna read this whole thing, but this is an email we got. Redacted, blah, blah, blah. Redacted seriously, uploaded my entire day. Eight guys, well-designed as ever. So when I started thinking in, I felt like I was witnessing a double rainbow. Then when I found the API builder, it went beyond a double rainbow to a level that I can only imagine is equal to witnessing a unicorn purple. What does it mean? What does it mean? Second thing, you can get by building an awesome API that is rich, or maybe less prass that you can, you know, whatever, work for yourself, control your destiny, give you something that's just as powerful as you can make a fool of yourself. This is really, I think, a big trend in technology right now. Here's some research group that thinks that spending and cloud computing is gonna more than double over the next four years. This is a major sort of wave. I think we're kind of at an early stage in this process of more and more infrastructure, more and more technology being done in this way. You see this big crop of startups, literally probably hundreds of startups that are approaching technology in this way, and a number of them are gonna do well. But there's plenty of space. Again, this isn't really in this world. I think there's plenty of space in this world where you're gonna be able to see what's happening in this world. I think there's plenty of space for awesome technologies delivered in this way. So if you're looking for some ideas, you do like high-five for Rudy. High-five is early on, and you probably find some amazing things that high-five hasn't thought of. You know, do maybe whether this is Rudy or not. This is sort of a new unexplored territory. Two other ideas I think are kind of cool that I'll probably ever build, but what about the API to the government? Is there any light filling out for, is it like the DMV? Some of my labs. Some of my labs. Yeah, some of my labs. Do they actually use, do they actually provide interactive access to? They're actually a product, which is a data catalog of other APIs that exist in various governmental organizations that are about this federal, state, or most powers. So provide this enormous functionality in a simple, convenient way. People are going to build the amazing tools for that. Or what about the API to manufacturers? So Amazon ECQ is like a server farm in the cloud. What if you had a farm of 3D printers, and people can make the API request to you and say, I would like a thousand, or whatever, and you can give them a spec, and they'd go beyond there and do like you know, classic folding and laser cutting and all that. That'd be pretty sweet. Now finally, APIs can allow you to change the world. Back in like 1999 or 2000, there was a bubble in technology. And companies were raising, you know, $10 million without having a revenue or a product or an idea. And most of this was hype, but there was one kind of reason for this. And that said, it was expensive to start a technology company in 1999. You had to pay a lot of money to Larry Ellison, and you had to like buy, you had to buy like your web server from Nescape, and you had to like buy from Operating System, et cetera, et cetera, et cetera. So what happened? You can source, Richard Stallman happened. And today, you can acquire a better technology that was available 10 years ago for $0. That's really powerful. What that does is allows us, previously, we, the hackers were like beholden to the Harvard MBA students. They would get rich or become VCs or whatever, and we'd have to go ask them for money in order to do things. And that's not true. And that's really powerful. Now we ask for $20,000 from Paul Graham. Or we don't ask for anything, and we bootstrap, and we end up in some business magazine, like 37 singles. And that's really cool. It's how Facebook and Justin Timberlake work together. So I think Open Source is the technology revolution of the 2000s. It absolutely changed the game. And I think Jeff Bezos at Amazon is running the technology revolution of the next decade of this era. And it's going to be another kind of small, small things to do awesome things that they couldn't do before. Thanks. Thanks, thanks, I appreciate it. And what we did there is equally applicable to you, honestly, any API that we have to pass data. Some APIs are more read-only, just like getting data. How hard would you think it would be to extend your DSL and support enough information to allow you to automatically build that API request bill? Yeah, absolutely. And API, actually, API validation. So documentation validation. We would love to do that. Ask Brandon in the back. You mentioned Jason and XML but what about not as structured as you are out forming for me? What are you about for that? The problem there is you can't do GASP. Or you can't. Rails does GASP through brackets. But I can't do that. If it's simple, I think that works just fine. Same thing with just coasting variables. You can do a lot of the same things. But if the data needs more structure to be representative, that's good. Do you think the rules change a bit in GASP versus public confessing API as things as far as what match you're accepting? Is Netflix that good? You posted recently saying don't use building these huge even the high-scale services. Use things like protocol numbers. So the question is do the state rules apply for it internally? Yeah, did Netflix recommend that for the internal systems? Yes. Yeah, I think it does because if you're doing it internally you can basically set up as an expert API. And two-thirds of what I talked about there was about making it seem easy to learn in preschool, etc. Yeah, you can worry about some of those things. I'm sure some of the stuff is the same as being the I'm sure. I think what he mentioned about some of the protocols and that you would do on an internal API where you know your infrastructure but I think the things that you've done in ZenCoder and the things you do to make your API easy are just as important internally because you're going to go through developers, you're going to go through people, additional teams are going to take on responsibilities to use those internal APIs so you should not skimp on that side of it just because you're developing for your and house resources. You pay them more than you do your customers. Yeah, that's good. I'm going to take my card during your presentations to let somebody outside apologize if this was covered but... Authentication for APIs in ZenNet is it off the way of the future or what? I didn't cover that. Do you think it's off the way of the future? No, no. It's part of the future. It's not the whole future because you have a situation where you have two servers that you love and you need to talk to each other about it. Sure. It only applies to more third-party situations. I didn't talk in detail about different authentication but it's part of that and I don't think I have a strong opinion of what the best one is but if anyone does there's no single one. There's more than one. Are you just going to make sure that the documentation is up to date and correct? Yeah, how do we make sure it's up to date and correct? We don't do it perfectly so I'm sure this stuff and our documentation right now is not. If we did have integrated docs and request builder and validation and all that we'd be forcing and that'd be great. One thing I didn't talk about here too is something that we don't do. We don't wait until this API setting is coming in. We shouldn't and we will in some ways continue to do that. Which means that if someone like this smells an API key it just like silently fails. That's not ideal. Much better to tell them this is not a recognized API key. You do that by waiting for someone to come in and reject your request for things that aren't there. So that would also help us keep documentation more up to date if things fail too often because of that kind of thing. Specifically have you considered using Cucumber a framework like that or not not in detail but if you could do all those things put together that would be really powerful. If you just want another data point break back here for the past 15 minutes oh yeah actually there was somebody who gave a presentation on that I forget where but they're basically mapping their feature set into documentation. So using Cucumber like your specs or your app to generate your documentation so know that your docs are in sync with your application. Read me your designs. Read me your designs. Read me your designs.