Building Your API for Longevity
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 65 | |
| Author | ||
| License | CC Attribution - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/37595 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language | ||
| Producer |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
Ruby Conference 201456 / 65
2
3
4
6
9
11
14
17
18
19
20
25
27
29
30
32
34
35
39
40
46
47
50
53
55
56
58
61
63
00:00
BuildingCodeSoftware framework
00:30
CodeOpen sourceFinitary relationControl flowSoftwareEnterprise architectureHypermediaTerm (mathematics)Theory of relativityWeb pageRight angleSoftware frameworkImage resolutionFacebookMereologyPoint (geometry)HypothesisComputer animation
01:56
MathematicsRobotMereologyEnterprise architectureSoftwareDifferent (Kate Ryan album)ServiceroboterPower (physics)KälteerzeugungOrder (biology)Revision controlMathematicsInternet der DingeInformation securitySoftware developerComputer animation
03:29
BuildingTerm (mathematics)BuildingTerm (mathematics)Software developerMultiplication signCoefficient of determinationMathematicsRevision controlSpectrum (functional analysis)Computer animation
04:11
Term (mathematics)Design by contractDesign by contractBitEvent horizonRevision control2 (number)Computer animation
04:43
Design by contractControl flowDesign by contractCodecCartesian coordinate systemSoftware developerMultiplication signHypermediaWordComputer animation
05:31
BuildingAuthenticationInformation securitySoftware developerServer (computing)Software developerType theoryService (economics)Interactive televisionProxy serverData managementServer (computing)Scaling (geometry)Internet service providerPoint cloudOcean currentComputer animation
06:33
Group actionProcess (computing)Service (economics)Ocean currentBuildingCodeService (economics)Design by contractClient (computing)Computer animation
07:36
Service (economics)Electronic mailing listGroup actionMessage passingGroup actionSoftware developerInteractive televisionElectronic mailing listService (economics)Modal logicLine (geometry)INTEGRALLevel (video gaming)Revision controlComputer animation
08:40
Message passingProduct (business)Decision tree learningElectronic mailing listMessage passingHypertextProcess (computing)Electronic mailing listLink (knot theory)Pi
09:17
UsabilityRemote procedure callPartial derivativeFile formatBuildingData typeFile formatLibrary (computing)Software developerUsabilityPartial derivativeArithmetic meanComputer animation
10:02
Data typeBuildingDesign by contractUniform convergenceInterface (computing)Physical systemCache (computing)CodeServer (computing)Client (computing)Constraint (mathematics)Different (Kate Ryan album)Physical systemIntegrated development environmentServer (computing)Constraint (mathematics)State of matterPlanningStandard deviationHypermediaPartial derivativeComputer animationLecture/Conference
10:49
Type theoryProduct (business)PlanningBookmark (World Wide Web)Term (mathematics)Goodness of fitReal numberComputer animation
11:45
CodeRight angleTerm (mathematics)Cartesian coordinate systemMultilaterationComputer animation
12:31
Software developerService (economics)System programmingComputing platformRevision controlDependent and independent variablesJava appletCodeRevision controlSoftware developerMathematicsDifferent (Kate Ryan album)Service (economics)Mobile WebSoftware maintenancePatch (Unix)Cartesian coordinate systemMultiplicationPhysical systemComputer programmingMultiplication signSystem callComputing platformMessage passingFunctional (mathematics)Logical constantProgramming languagePower (physics)Internet service providerWordPoint (geometry)File formatComputer animation
14:39
Keyboard shortcutAdditionFeedbackTerm (mathematics)Spectrum (functional analysis)Software developerCodeLine (geometry)Single-precision floating-point formatKeyboard shortcutComputer animation
15:15
CodeFeedbackModal logicStandard deviationCodeUniformer RaumModal logicSoftware developerGraph (mathematics)Type theoryProduct (business)FeedbackSoftware design patternForm (programming)ConsistencySpectrum (functional analysis)FacebookMathematicsService (economics)Computer animation
16:09
Hybrid computerSoftware testingStandard deviationSpectrum (functional analysis)Software developerHybrid computerBuildingMathematicsCycle (graph theory)Level (video gaming)Hand fanComputer animation
16:41
FluidContinuous functionFluid staticsCycle (graph theory)Software developerCycle (graph theory)CodecDirection (geometry)Phase transitionView (database)MathematicsMultiplication signPhysical lawPrototypeFeedbackProcess (computing)System callReal numberComputer animation
17:42
Software testingIterationArc (geometry)Client (computing)CodeWebsiteSoftware testingCuboidCodeMultiplication signConsistencyMathematicsFeedbackPrototypeSoftware developerComputer animation
18:28
Constraint (mathematics)Pattern languageSoftware developerCoding theoryPrototypeVideo gameReynolds numberPiFlow separationScaling (geometry)Computer animation
18:58
CodeLine (geometry)PrototypeSoftware developerClient (computing)PrototypeSystem callRepresentation (politics)CodeDependent and independent variablesSoftware developerLine (geometry)MathematicsVisualization (computer graphics)Online helpSoftware design patternComputer animation
19:36
CodeJukeboxDependent and independent variablesCodeSoftware design patternComputer programmingCentralizer and normalizerComputer animationSource code
20:04
Revision controlCodeSoftware testingMathematicsCodeProfil (magazine)MereologyWindowAdditionComputer animation
20:36
HypermediaData typeContent (media)Codierung <Programmierung>EmailError messageMessage passingPatch (Unix)Software developerAdventure gameExtension (kinesiology)Patch (Unix)HypermediaType theoryTerm (mathematics)Row (database)Group actionParameter (computer programming)Address spaceCartesian coordinate systemComputer configurationPhysical systemWordValidity (statistics)CodeBookmark (World Wide Web)Multiplication signGame theoryVulnerability (computing)Different (Kate Ryan album)Power (physics)Link (knot theory)HypertextClient (computing)Web crawlerRadiusFormal languagePlanningComa BerenicesState of matterMathematicsReading (process)Computer animation
24:22
HypertextLink (knot theory)Vulnerability (computing)HypertextCartesian coordinate systemFormal languageLink (knot theory)Dependent and independent variablesComputer configurationComputer animation
24:49
Message passingHyperlinkData typeContent (media)EmailDataflowMessage passingContent (media)Computer configurationType theoryLink (knot theory)SubsetHypermediaEmailPresentation of a groupMathematicsException handlingComputer animation
26:13
EmailFile formatType theoryContent (media)Data typeFormal languageContent (media)Right angleComputer architectureCodeDependent and independent variablesInterpreter (computing)Exception handlingCartesian coordinate systemEmailType theoryMathematicsFilm editingCodeMaxima and minimaProcess (computing)File formatHypothesisNP-hardStandard deviationComputer animation
27:36
Dependent and independent variablesCodierung <Programmierung>Web pageData typeHypermediaServer (computing)Error messageDependent and independent variablesCodeCodeRight angleWeb pageError messageHypermediaMathematicsType theoryAreaLatent heatComputer animation
28:23
Message passingError messageError messageUsabilityDescriptive statistics1 (number)Multiplication signReal numberMessage passingInformationSystem callComputer animation
29:24
Exception handlingCodeMessage passingLink (knot theory)WebsiteInformationSoftware developerInformationSoftware developerError messageLink (knot theory)Group actionDescriptive statisticsVotingDependent and independent variablesSynchronization
30:07
Complex (psychology)Software developerEndliche ModelltheorieSoftware developerBuildingSynchronizationProjective planeNumberOpen sourcePoint (geometry)Spectrum (functional analysis)SpeciesBranch (computer science)Computer animation
31:00
BuildingTerm (mathematics)Line (geometry)Cycle (graph theory)MathematicsSoftware developerInheritance (object-oriented programming)FeedbackAnalytic continuationPrototypeTerm (mathematics)Computer animation
31:53
Group actionMereologyCodeCore dumpSpectrum (functional analysis)Software developerTerm (mathematics)Computer animation
32:44
MereologyService (economics)CodeCartesian coordinate systemMathematicsType theorySoftware developerDifferent (Kate Ryan album)BlogSoftware bug40 (number)WritingSoftware frameworkRight angleProduct (business)Series (mathematics)Content (media)InformationMultiplication signHypermediaComputer animation
33:51
Series (mathematics)BlogTwitterEnterprise architectureMultiplication signVideo gameSpeech synthesisComputer programmingPresentation of a groupSoftware testingPoint (geometry)Computer animation
34:37
Game theorySoftwareEvent horizonVideoconferencingSoftware testingComputer programming
Transcript: English(auto-generated)
00:19
API for longevity talk.
00:21
If you're not here for that talk, you're in the wrong place. Quick disclaimer, I don't know how to work tech. This is not a talk about how to code your API. If you're like, hey look, I want to know how to use a framework, I'll learn how to code it. There's great tools out there. Rails API is a great framework.
00:41
Grapes out there. We're actually talking about things that you need to know to build a successful API long term. So a little about me. First and foremost, I'm an API fanatic. Otherwise I wouldn't be doing this talk. I'm doing this talk because I've had problems with APIs. How many people here have used an API? How many people have used just hypothetically
01:03
a giant social media network API that breaks every two months? Nah, just hypothetically. Is that like fun, or is that annoying? You're still a giant, yes. Are you with Facebook? Okay, as I get fired.
01:22
The other thing I want to point out is that I'm in dev relations with MuleSoft. I want to thank MuleSoft because they're the reason I'm able to be here. And that's the other reason for this talk. MuleSoft deals with enterprises. We serve about 30% of the global 500. So a common opinion that you're all very familiar with. And so we talk about these best practices and these issues.
01:40
These aren't just things that I'm saying, hey look, these are things you can do to make your API last longer. These are actually things that even the largest companies forget to do. This is the same advice that we give the Fortune 500s, the Global 500s, that we're gonna give you guys today. I think we already know this. APIs are changing the world, right?
02:00
I mean today, there are over 13,000 public APIs. 13,000 of them. And the best part is that doesn't include all the mobile APIs. That doesn't include all the enterprise APIs. That doesn't include network to network APIs. That's just public APIs. There are hundreds of thousands of APIs out there. And these APIs are powering
02:21
and connecting tons of different things. They're connecting phones, watches, glasses, cars, refrigerators, thermostats, in-home robots, and more. Why don't you guys think about that? Everything is becoming connected by APIs. Your home security system, connected by APIs.
02:44
Soon you're gonna go home, and it's not gonna be, oh, you arrived. Your house is gonna say, oh, he's leaving work. There's traffic over here. We'll know all these different things. Just think how this can all work together. But in order for the internet of things to work, APIs need to remain persistent.
03:01
Because you don't want a security system that says, hey, somebody broken your house? I need an update. Sorry. The other thing that we forget about APIs is versioning and making changes is very, very expensive for everyone. It's not just expensive for the company
03:20
to version their API and have two different versions that they have to support. It's expensive for the developers who have to migrate to that new version. Thankfully today we're gonna talk about five very simple steps, five simple concepts, that you can use to build an API that lasts. They are go with a long-term mindset.
03:41
That seems kind of like a no-brainer, like duh. But if you don't think long-term when you start, if you think, I'll just version it when we need to make changes, you're not gonna be successful. You also need to understand what you're building. Another, duh. But most companies do not take the time to understand what they're building or why they're building it.
04:02
You don't like something called spec-driven development, which we're gonna talk about. And then following best practices and repeating those steps again and again and again. Think about the long-term. Think of your API as a contract. Forget about versioning for a second. Put versioning outside of your mind.
04:20
This is my favorite slide, by the way. How many people here are designers? Okay, he's looking down, he's like, no, I don't even wanna talk to this guy anymore with that. You're not that good at design. And people are gonna be like, no, I don't believe that. I'm gonna prove it to you. You can pay a little bit now, in advance, or you're gonna pay a lot more later. And you need to think things through.
04:41
The mindset is everything. Here's the thing with your API. Your API's a contract. When you use the social media API and it breaks, what's your first thought? I'm gonna, yeah, I'm gonna call them this, give them a gift basket, thank you. I like the dude, they're just dude, why'd they do that?
05:00
Now imagine if that API was critical to your business's success. Because a lot of APIs are. And when you break backwards compatibility, when you break that contract, you're, as an essence, telling the developer, here's something you can use, but it may not always work. My word's eh, okay. And not only are you costing them the time
05:21
to build that application, you're preventing them from focusing on features. So we need to step back and say, no, it isn't okay to break backwards compatibility unless we absolutely have to. That means you have to think through every aspect of your API. You can't just build it, you have to think it through. Think about who is your API for?
05:41
What type of API are you building? Are you going to maintain your API, how so? How are you gonna document it? How are users gonna interact with it? How are you gonna manage things like authentication, provisioning, throttling, protecting the developer's credentials? What about attacks against your server? And then how are you gonna manage support? Now we're not gonna go over the last three or so
06:01
here today in depth, but this is one of the most important things you can do. When you build an API, you wanna find a management tool for it, a proxy for it. Whether you build your own and put it in the cloud, or whether you go with another service. And here's the thing, I'm with MuleSoft. MuleSoft is an API management provider. This is where I get fired. I don't care if you use MuleSoft,
06:21
if you use Mashery, 3Scale, Layer 7, IBM, Intel, I don't care. You should probably look at a solution, find a solution that meets your needs, and have that layer of protection. And then think about how you're gonna manage support. But as you build your API, who are your end users? We forget this. We say, who are we actually building for? We're building it for current customers,
06:41
for business partners, for third-party services. One of the things I love is we say, hey, we're gonna build this API, and we forget to talk to the clients. So I had the privilege of contracting with a company, and we spent six months building this amazing, amazing API. Now, it was written in PHP, so please don't judge,
07:03
but it was okay. And we launched this API out in the public. And I know the code was perfect, because I wrote it. I don't know why people are laughing at that. And three weeks later, we realized we had a problem. No one was using our API,
07:21
because it didn't meet their needs. We spent three months on top of that, trying to fix it. You know what we did with that API? We scrapped it. Gone. All because we understand who we were doing the API for and what they want to do with it. List out why you're making the API.
07:40
We get all these big companies that come to us and say, we want to build an API. That's awesome, what do you want to do it for? We want to expose our data to our users. Okay, that's a good start. But then what? You'd be surprised how many companies can't answer that question and were like, what do you mean? What do you want them to do with that data? What do you want them to do with your services?
08:01
How will they interact with your API's existing services, your other services, and services they would use with integration with your API? List out the actual actions that you want to do, or that you want them to do. And here's my two major lines for all the developers out here. First off, do only what is necessary.
08:20
When you build an API, especially when you build that first version, you're building the foundation. And you can get really, really fancy, and your house is going to crumble. Do only what is necessary, don't get fancy. Don't reinvent the wheel. Don't try to get creative. Don't try to create your own spec. Don't do it, it's not going to work.
08:40
Instead, list out what they need to do. At this stage, we're not thinking about CRUD. We're not thinking about how the API's going to work together. We're simply saying, hey, we have users. They want to create a user. They want to message a user. And then you notice in messages, we say, hey look, they want to send a message to a user. It's okay to put it in two different places.
09:01
Why? Because as you evaluate your API, you can say, okay, these need to work together, and this should probably go in the messages resource, but maybe we want to put a hypertext link in the users resource for that. So list out all the things that they can do with it, or that you want to be able to do, so you're thinking the whole process through. And then, are you building a REST API? Are you building a partial REST API?
09:23
SOAP, RPC? Which one of these should you build? Anybody? Okay, I hear REST. And I'm inclined to agree with you, but the answer is it depends on what your customers need. If you're working with large legacy companies, where like, hey look, we have all these SOAP libraries,
09:42
and that's what they're using, that's what they're comfortable with, it may make sense to build a SOAP API. Yes, I feel dirty saying that. But why are you building that API in that format? What's it gonna mean for your development? What's it gonna mean for usability? What's it gonna mean for longevity? And you shouldn't just say, we're gonna build REST because everybody's using REST.
10:01
You should know what the advantages are compared to SOAP, REST, RPC. You'll notice that with SOAP and RPC, they're very tightly coupled. Know the different issues with it. Also, don't just say we're gonna do REST without understanding the constraints of REST. Do you understand what REST means? Do you understand what it means to do client-server,
10:21
to have a stateless environment, to have a cacheable or layered system? So do your research first. Because here's the secret. Most APIs are not RESTful. Most APIs are RPC, or partial REST. Dr. Roy Fielding said, hey, let's not play semantics. If your API does not include hypermedia,
10:42
it's not RESTful, it's not REST. And given the fact that he created the dissertation about REST, I think we go with that. And this is why it's important to understand what you're doing with your API. Because if you don't understand, you're gonna deviate from that status or that plan. One company was sitting here going, hey, we got this API, we wanna build this out.
11:04
Let's use JSON here and HTML here. Let's do a queer string, a post here, and then do a JSON, a post here. You wanna know a secret? It really didn't work out well. And that also means thinking beyond today. That's another mistake we make, is we say, okay, we're gonna build an API
11:21
for today's roadmap. This is what our product's gonna do. This is what the API needs to do. You have to think beyond that. You have to think two, three years down the road. You have to think, what can the API do when you have new features that you've never even thought about? Here's my favorite quote from Al Gore. You have to expect the unexpected. Now I'm gonna go back to that design phrase
11:40
where I said you guys aren't that great at design. And I'm gonna probably get kicked off here. Dr. A. Philan puts it very succinctly. He says, hey, we're really good at short-term design. We're usually pretty bad at long-term design. How many people here have written code? Just a few people. Okay. How many people have looked at that code a year later?
12:02
How many people said, that is the best code I wrote ever? How many people have started building an application, and then three months later you're like, I'm boxed in, I can't go any further. I put myself in a corner. Because we're really, really good at short-term design. The problem is that if we think about the now and we don't evaluate for the long-term,
12:21
we're gonna get issues. And that's why we have to think long-term right off the bat. That's why we have to plan not just for a day, but for the future. And this is why we have to be very, very careful in everything we do. Which brings us to versioning. One of my favorite things with versioning is we say, oh, if we need to make a change, we'll just version the API. Versioning is a necessary evil.
12:42
It's not something you wanna do. Versioning should create several different problems. First of all, there's backwards incompatibilities. Multiple services they maintain. Creates confusion among developers. Before MuleSoft, I worked at Constant Contact as their developer evangelist. And right as I started, we launched V2 over API.
13:00
By the way, my shameless plug for Constant Contact, you should check out your API. The problem was that now we had two different systems we had to support. We had two different systems we had to maintain. Two different systems we had to do patches for. I got a call one day from a developer saying, hey, I have a problem with your API. Like, oh, no problem. Which version are you using?
13:21
Your version? Oh. Well, so how does it work? Oh, well, I make a post request and I get data back. And I kid you not, I was like, okay, is it JSON XML? He's like, I don't know, I just make a post request. We spent 30 minutes trying to figure out what version of the API he was using, and then developer adoption is nearly impossible. You're gonna be maintaining both APIs
13:41
for a very, very long time. You should version, and you should plan to version your API when you have backwards incompatible platform changes. In other words, you change your platform completely. The UI changes, the service change, everything's different and no longer functions the same way. Then it's time to version your API. Your API is no longer extendable,
14:01
basically what we're trying to avoid. Doesn't work anymore. Or your spec is out today and you're using SOAP and your customers want REST. But you should not version your API if you're just adding new endpoints or you're just adding new data or you're changing technologies. Apparently going to 2Ruby, which is a new format of Ruby that I'm working on. You should not do it because you change
14:21
your application services. Your API should be decoupled from your service layer and also from your technologies. If you're using Twilio to send SMS messages and you switch SMS providers, that should not affect your API. If you change your programming language, it should not affect your API. It should be separate. And versioning does not excuse poor design.
14:44
And here's the thing. With that API that we spent six months on, we spent six months building that API, three weeks trying to figure it out, and another three months where we finally basically spent 10 months on this thing to throw it away.
15:00
Wasted hundreds of thousands of dollars. You can either do the work upfront or you will pay for it long term. There are no shortcuts. There are no quick fixes. But there are things we can do. One of the things we can do is something called spec-driven development. And with spec-driven development, we can actually define the API before we write a single line of code.
15:21
We can use design patterns to ensure that it is standardized, normalized, and uniform across the entire form of the API. We can actually mock the API, send it to users, get feedback from the users, and find out what doesn't make sense. The Facebook API has an old graph inconsistency. And the problem is, they didn't catch it.
15:42
They didn't know about it. And now, if you do one type of search, it works this way. If you search ODA a different way, it doesn't work. And so they're like, hey, this is a problem, but it's too late. It's in production. People have found the workaround. We can't change it. It allows you to make necessary changes, again, without having to write services,
16:00
without having to write code. And one of the big things with spectrum development is you write code to the spec. You don't write the spec to the code. And you don't deviate from the spec. And here's where, again, where I get killed by people. Spectrum development means taking the best of two worlds. You're gonna take a hybrid between agile methodologies,
16:21
and then when it comes to the spec, once you have done the agile cycle, a waterfall methodology. Basically saying, this is the spec. Now it's not changeable. This is our documentation. We're building to the documentation. Of course, so I don't get killed on stage, I'm a big fan of agile. Love agile, and I would encourage you to use agile for the development, but once you have your spec,
16:40
it should not be changing. In essence, you wanna do a two-cycle approach. You wanna do the design phase, and then once you design it, you wanna move one direction, one way with development. Just have a larger look at the agile design cycle. The first thing you do is you define your spec. And then you prototype it. You mock it, let people get feedback,
17:01
and tell you what they like, what they don't like, what makes sense, what doesn't make sense. Let them make calls against it as if it was real. Get user feedback, because then you can say, this works, this doesn't work. And if your spec is perfect, go on to development. If it's not, make some changes in your spec, prototype it, get user feedback,
17:22
and just continue that cycle until you have the perfect spec, the perfect blueprint. And people say, but that adds a week to two weeks on the whole cycle. It does. But that's gonna save you that three weeks of, oh, this doesn't work, and that three months of, oh, we can't save it. It's gonna save you a lot of time, a lot of energy,
17:40
and a lot of money in the long run. The goal here is about using agile user testing, and carefully designing a prototype of your API. You're gonna find 99% of the issues with it. Most APIs do not fail because the code's bad. Most APIs do not fail because the end point didn't make sense. They fail because there's inconsistencies
18:02
that eventually box them in, where they cannot expand it any further. Another thing to think of, how many people here have done work for clients? Let's say you're working on a photography website, they say, look, I want a black website with these pictures, you build that, it's absolutely perfect, right? No changes.
18:21
Same thing in API development. Why do we try to say, we're gonna do this perfectly without getting user feedback? Of course, the problem has been, it takes a lot of time, a lot of energy, a lot of money to build those services and write that code. The good news is that there are now several new specs out there that allow you to do this and make it very, very easy.
18:40
There's Ramble. Ramble's backed by several, several different companies in the industry. There's Iodocs backed by Masri. There's Swagger, which is Reverb, Apigee, and Threescale. There's API Blueprint, which is Apiary. Personally, my favorite, and of course I'm biased, with MuleSoft, is Ramble. And the reason I like Ramble is because it'll allow you to do several things with your API.
19:01
You can define your API in just a few lines of code. You don't actually have to write Ruby to build your API's mock. You can see what it will look like as you go, which means you actually get visual representation of your API as you build it. So you can look at the responses and say, this response makes sense, this one doesn't. You can quickly prototype it. Here's the great thing about prototyping it.
19:21
You can send the code or the URL to developers around the world, and they can make calls against that if this was a real API. You can quickly make tweaks and changes. You can use it to document, use it to interact with your developers. You can even build SDKs. But what I really like about Ramble that makes it unique is you can do design patterns and code reuse.
19:41
And this is very, very important when building out your API and building your spec. Because if you use design patterns, if you use code reuse, it means that you're gonna have a normalized resource style. If all your collections work similarly, and all your items work similarly, then you know that there's not gonna be a large deviation from them. They're nice about Ramble,
20:01
and actually all these specs is they have visual designers, and this is what Ramble looks like. Very, very simple to use. But remember, your spec is not a one and done thing. It's a blueprint for your API. Just like you're gonna add a new addition to the house, you don't just say, okay, I'm gonna tear this part of the house down, put a window there, put a window there. You plan it out, you say, this is what I'm gonna do.
20:22
The same thing with your spec. You should never have code that changes a resource or changes a method that's not defined in your spec. Your spec should be your blueprint to say, this is what you want things to do. And then the next thing you wanna do is incorporate best practices.
20:40
This is going to ensure that your API meets your needs. What you wanna do, you wanna use nouns. With REST APIs, you wanna keep them as loosely coupled as possible. With any API, you wanna avoid tight coupling. By using nouns and saying users, you can create multiple methods on the user
21:01
versus having it tightly coupled, I wanna create a user, I wanna get a user, I wanna delete a user. The other problem with this is you can run into ambiguous terms. You can run into things that are very similar. For example, I saw one API where it was delete user, delete user by ID.
21:21
What's the difference? And they have fantastic documentation. Utilize CRUD. This is actually my favorite thing because I'm from Minnesota originally and we always go, oh CRUD, and nobody gets it. CRUD stands for create, read, update, and delete. There are five main methods you wanna use.
21:42
The first for create, you wanna do a post. For read, you wanna do a get. For update, you wanna do a put or a patch. Now, put and patch are very specific. Put is a complete overwrite. If I do a put and I don't put a first name in there, the first name gets overwritten and is now blank.
22:03
Put says update the record exactly as I give it to you. All of it. Patch, on the other hand, says I wanna patch that record. Therefore, if I give you a last name and I give you nothing else, the only thing affected is the last name. Nothing else gets modified. It's very, very important that you take the time to understand CRUD because users and developers
22:21
are gonna rely on this to interact with your API. And then delete is super complicated. You just use the delete HCP action verb. Now, I'm gonna say the scary word of the day. Use hypermedia, or HADIOS. HADIOS stands for hypermedia as the engine of application state,
22:41
which is a really fancy way of saying that when people use your API, you should be directing them to what they can do next, that it shouldn't be stacked. They shouldn't have to know the URIs to your API. And people like to give these big arguments about HADIOS and make it really complex. Friend of mine, Dr. Keith Casey Jr.,
23:02
likes to describe it as create your own adventure book. If you open the book and you say, I'm gonna go here, and this is okay, you went here. You now have two options. You can go here, or you can go here. That's exactly what HADIOS or hypermedia is. It's telling what their options are.
23:22
Another way to think of it is, if you go to yahoo.com and you want to view the news, do you go back to your address bar and say yahoo.com slash news? Or do you click the news link? And then we won't read a story, do you type in that URL, or do you click that story link?
23:42
That's what we're doing with hypermedia, is we're sending back actions, we're sending back links, telling them what they can do next. And what this does is it provides an extensibility and flexibility to your API, where if implemented correctly by the client, if something needs to change, maybe you need to add extra validation. So you had a messaging system with the ID,
24:00
and you realize, wow, people are just spamming people. This doesn't work. We're gonna add a last name just to make sure they send it to the right person. Prior to hypermedia, that would break backwards compatibility. It would just stop working. They'd have to update their code. With hypermedia, if they used the hypermedia links, it would automatically work for them. They wouldn't have to change anything.
24:22
Now with hypermedia, don't reinvent the wheel. There are several specs already out there. There's how, which is the hypertext application language. There's JSON-LD, a JSON language definition. There's JSON-API, siren, and many, many, many more. Each have their strengths and weaknesses. One of the great things about how is it's nestable,
24:42
which means that if you get response to the collection, each item can have its own hypertext links. And how complicated is hypertext links? This is what they look like. You'll notice that we have our data returned, but under our data, we say, hey, here are the links. Here are the options of what you can do. We have edit.
25:00
This is the link to use if you wanna edit the user. We have message. This is the link if you want to message the user. Again, a very simple flow that says, these are your options. The nice thing about hypermedia as well is what if those options change? Because REST is stateless. What if you can no longer message the user?
25:21
How do you address that with your API? How would you address that in the hypermedia? You just remove the link. Say, hey, it's not there anymore. That's no longer an option. So it gives you a lot more flexibility with your API. If you add new resources, you add new options. All you have to do is add it in the hypermedia,
25:42
and those are now immediately available to them. Even though they built their API, they can take advantage of that. Now, one of the biggest best practices that gets missed, and I did a presentation at API Strata, and I even forgot to mention it there. You wanna take advantage of header tags.
26:02
You wanna take advantage of accept and content type headers specifically. The reason for this is because it now creates a very flexible API. Let's say your users are using XML. That's what they're used to, they want XML. And then you have users that says, I want JSON.
26:21
If you're not using the accept header or the content type headers, you basically say, oh, I'm giving you XML, tough. But if you use those, you can say, okay, if the content comes in as type JSON, I'm gonna return JSON. If it comes in as XML, I'm gonna return XML. The nice thing about this is
26:41
if there's a new standard that comes out, if something changes or you have a customer that has a very specific need for a very specific content type, you are flexible enough where you can adjust to that, where you can adapt to that. So it's very, very important that you use the content type and the accept headers and respond to them that way. Hypothetically, when you build your API,
27:02
I should be able to send a content type JSON with an accepts XML. And you should be able to send me XML back, hypothetically. When you build your application, you should not have that hard code layer. You should have an interpretation layer built on top of your application to send back the type or the format that they want.
27:23
Keep in mind that REST requires a uniform interface, so that'd be a violation of REST. You don't wanna do that. You don't wanna give them XML if they send JSON. But your architecture should allow you to do that. It should be decoupled enough that you can do that. Also, send back response codes. Make sure you use the right response code.
27:42
Very commonly, you'll do a post request and you'll get a 200 back. That's not the right response code. 200 OK is not correct for something created. You wanna use a 201. So know your response code and use them. If they make a request and maybe there's an error, tell them they need an error. But maybe they make an update and nothing changed.
28:02
Send them back a 304. Nothing changed. Let them know that. Tell them they're not authorized or forbidden. Tell them the page doesn't exist. Tell them they're requesting an unsupported media type. If I do XML and you only support JSON, let me know. Give them a very specific error code. And if you're really feeling creative,
28:21
you're like, look, I wanna go the extra mile, you can send them back one of these. Keep in mind, 418, you should only send if you're actually a teapot. 420, some of you will get, some of you won't. Kudos to the ones that don't.
28:43
In California, that's like, no, everybody's like, yeah, we know what it is. Also use descriptive error messages. One of my biggest, biggest, biggest pet peeves, and actually a big downfall to APIs, is they're not usable. They don't provide good usability. I went to an API and I made a call,
29:02
and I got back an error message that said, this didn't work. I got another one, and I kid you not, this is a real error message that said, we're sorry, we're bleeding a rocket ship. I'm not gonna lie, I nearly drove from Minnesota at the time down to wherever they were to go visit them and see this rocket ship.
29:23
I was not happy. Give them as much information as possible. Tell them what's wrong. Give them an actual error response. And go the extra mile. Give them a description. Say, this is what went wrong. Tell me explicitly. Working with one API, no matter what happened,
29:41
it said, this action's not authorized. I spent 45 minutes to find out that I was missing an ID. Tell me I'm missing an ID. Make it easy on me. If you can, put a link there. Give them the information to fix it. Because one of the biggest downfalls to APIs is people can't use them.
30:00
And if developers can't use your API, no matter how well thought it out it is, no matter how much work you put in it, it won't be long-lived. And that goes with documentation as well. Make sure your documentation stays in sync. You would be surprised the number of companies that say, look, our documentation's out of sync. We need to rebuild the API. Can't you just fix your documentation?
30:23
And this is the other advantage of spec-driven development, by the way. That spec you used to define that blueprint to say, this is what we want. That spec you created that let developers go fearlessly building your API. Because now instead of having three developers going down and saying, okay, you build that endpoint, you build that endpoint, you build that endpoint,
30:40
and let's hope they're the same, let's hope they work together, you know exactly what I'm building. You know exactly what I'm building. You know exactly what I'm building, and we're all building based on the same model. And now we can take that same spec and we can use it for documentation, without having to recreate new documentation, without having to change things using these open-source projects.
31:00
And then finally, when adding new things to your API, you really, really wanna be sure to go on with the long-term mentality. It keeps going through, the cycle continues. Everything you do, you need to follow those four steps. Even if you're just changing one simple thing, go back and say, okay, let's design this. Let's look at this, let's prototype this,
31:21
let's get user feedback. One of the hardest things for developers to do is say no. And immediately the reaction is, no it's not. But if you think about it, if I say, hey look, can you just add this? And you're like, oh yeah, it's two lines of code, super easy, I'll get that done in five minutes.
31:40
The problem is, if you make that change without thinking through long-term, you're looking at breaking your API down the road. That change may come back to bite you. So again, everything needs to be very, very carefully analyzed. It only takes one tiny, tiny little thing to mess up your API.
32:00
It only takes one little thing where all of a sudden you can no longer extend the API, you can no longer build upon it. And this is the secret to API longevity. There are tons of best practices out there. There are tons of resources out there that I encourage you to look at. But the secret to longevity is not saying, I'm gonna incorporate the best practices.
32:22
Because you can do all the best practices, but if you don't think it through long-term, it's not gonna work. You can have the best documentation in the world, but if you don't use a spec-driven development, if you don't carefully design your API step-by-step for the long-term, you're still gonna get in that corner
32:40
where you can't extend it. Because here's the best part about building APIs. Building an API, writing the code, is easy, right? I mean, you're literally saying, okay, this is what I want the code to do. Sure, there's the debugging aspect, but you're just writing code. There's frameworks out there, there's Rails API, there's grape out there that you can use.
33:01
But designing the API is the hard part. Because once you push it in production, you cannot take it back. Once it goes live, you cannot change it. So I would very, very encourage you to be very, very careful in developing your API. Use spec-driven development. I don't care if you use Rammel, I don't care if you use Swagger, API blueprint, look at a spec, grab it.
33:22
Incorporate the best practice that we talked about. Use Hadios or Hypermedia, use CRUD. Understand what REST is. Make sure you're accepting content types. And make sure that you're as flexible as possible. We build our applications that way. When we use an MVC framework, we try to make it as extendable as possible. We have our services layer, we have this layer,
33:41
like okay, we have all these things modularized so we can change it if we need to. The difference with MVC versus an API is you can't change it once you've done it and pushed it public. There's a lot more information at blogs.mulesoft.org. We actually have a best practices series that goes far more in depth. Unfortunately, we don't have all the time in the world to go into every little thing.
34:01
So I encourage you to check that out. If you enjoyed the presentation, I'd really appreciate if you sent a tweet to MuleDev and said hey, thanks for letting Mike speak. If you did enjoy the presentation, if you're like holy crap, this guy just wasted 45 minutes of my life that I will never get back, come see me, I give out bribes.
34:21
Thank you for laughing at that. The one guy's like aye. Last but not least, this is my shameless plug, one of the things that we're trying to do with MuleSoft because we work with these enterprise companies that struggle with these issues. We work with these companies that even though some of this may seem like common sense, they don't follow these practices and that's why they're so important. We're launching kind of a beta program where you can earn points, earn rewards,
34:41
get different things. For learning more about best practices and APIs, we're in a private beta. I'd invite you guys to join it if you'd like to. With that, I think I have a few minutes for questions. I'll see you guys in the next one.