 Cool good afternoon everyone. I hope you're at least a little bit awake after all the food that you've just eaten It's always a little tough in the lunchtime spot to keep you guys awake, but we'll see how we get on Just wait for a couple more people to come in It's always empty at the front. I Don't smell that much Dude Cool well, um, we'll get started anyway So I'm Christopher Holt This is your API is a UI part of the PHP track here at Drupal con This is my first time here. In fact my use of Drupal is Not very experienced. So so if I do any slip-ups Feel free to heckle feel free to to throw me your swag Anything you like just to keep us all awake If my clicker does want to work It doesn't Who is this guy? So I'm an engineering team lead at data sift We're we used to traffic everything on Twitter for our customers reseller on Twitter's behalf all in real time Now we're in your Facebook reading all your posts and comments and likes and providing aggregated analytics on that I look after the public web application and the public API So I'm responsible for the design and delivery of all these things. So I'm very much speaking from experience here prior to that I was a senior engineer at Timeout magazine if you've been to London, you might have got it for free New York, they're all over the world and I was very much involved in a web service oriented architecture Rebuild of the whole platform that allowed us to do multi-city multi translation capabilities I'm also the founder and Co-organizer of PHP Barcher a local user group in Reading We've been going a year now So if any of you ever come to the UK come along to Reading it's famous for being the home the the hometown of Ricky Gervais Yeah, and that's about it And me of course so so pleased to come along look us up come along speak who knows I Also act I Also shave This is actually a short beard for me So first off like I just said I'm not that experienced with Drupal so I'm gonna throw in a couple of examples that I've managed to find but in a general Sense, I'll be talking about APIs APIs both web services and the actual code that that we're writing I'm not gonna give you any opinions as to what the best API out there is I'm not gonna Jump off the fence there But I'm gonna give you a few opinionated examples of what I consider to be best practice And little things that can help you get along with your users and the the consumers of the software that you write As a quick hands up, can you put can you put your hands up if you don't enjoy audience participation? Sweet the joke works How many of you do APIs write APIs? That's quite a few of you how many of you write web services and how many of you write libraries and Modules thoughts are all of these are examples of APIs. There are ways in which that computers can interact with computers But one thing is kind of missing when we design our software We often think well, what's the easiest way that we can expose this to our customers so that people are gonna use our software But ultimately we're not necessarily thinking of the end users We're not necessarily thinking of the guy who's gonna be screaming you in the middle of the night when he hasn't figured out after five hours How to make your software work? So an API an application program is interface is an interface. It's a way in which computers talk to each other Interfaces in general are ways in which two systems or a user and a user or a user and computer and so on can talk to each other And us as humans we are built to figure stuff out. We're built to learn So the interfaces that are there in front of us can be very confusing to begin with but eventually we can work stuff out We can click around we can figure out what's going on Computers are finicky users. They don't really know what they're doing. They understand numbers They understand what you've told them to do, but if you present them with something novel it takes it Well apart from maybe Google with their their excellent AI stuff. It takes them a long time to figure out what's going on So as humans we have to tell the computers how to use these interfaces And as a result of that we need to understand the APIs that we're using and as a result of that The people creating the APIs need to think of us think of the low lead developer Think of the person who's going to be reading your documentation Looking at your code trying to talk to your web service and figure it all out and if it's an arcane mess of Inconsistency and of things that are not intuitive then that person is going to be cursing your name until the day they die Or at least until they get a new job, and they don't have to touch your stuff anymore So who are your users? Well, they're developers and your colleague developers They're your customers if you're selling a service If they're if they're buying your software if they're buying access to your product in your platform If they're building on top of your platform, and they're providing a service of their own They're customers so you not just the people who interact with you directly But those who interact with those who interact with you directly if that makes sense after lunch And any of the applications that are built on top of that you have all these People and systems and things to be considering when you're building this software when you're delivering the stuff to people So when you start approaching your API's when you start designing them and thinking about who you're going to deliver them to Think about how they're going to use them Come up with the use cases if I create this module that provides some programmatic access to my Drupal application Why do people want that? Are you doing it just because are you just exposing it on the off chance that someone will figure out that? They need that think of ways in which people are going to actually be Implementing software against your stuff and the use cases can help you understand that create user stories As a customer of mine, I want to Because I want to I want to consume the payments interface because I want to make a lot of money You know, that's quite a good driver money Document how those stories and use cases play out if you were the person interfacing with your software How would you go about? reading and using and consuming that service Lay all that out upfront Because that can provide a healthy guide and a map to the way that you can continue your integration Work in the in the first place and think about what kind of elevator pitch you can send to people Why would they want to use your API? Why should they use your software and not someone else's if you can Contain that in a couple of words in a couple of sentences And if you can include the word simple and easy to use and mean it Then people are a lot more likely to adopt your software as you're going on and Once you have those use cases once you have those stories and you can start to justify exactly Why you're exposing the API you have a cast iron set of examples as to the reasoning behind it So not only can it help guide the design, but it can help you understand exactly what you're revealing in the first place You don't really want to expose your business logic to people Just because you can you don't want it to be as close to the underlying code as you can you want to think about Reducing the complexity for very good reasons. You might have an object oriented system underneath of storing your data of Modeling everything you do, but your customer doesn't need to know that the the person the software that's Interfacing with that. They're only in it for themselves So think about the ways in which you can take that complicated object oriented model That's flexible as anything and boil that down to a more simple approach and Along with thinking what they can do Think about what a user cannot do Think about restricting them before you actually reveal this This interface think about the ways in which you're going to hold back Functionality the ways in which you're going to restrict them because nine times out of ten Your boss is going to turn around in three months time when you having published this API and said Actually, I want to sell it with only this bit and not that bit But that guy over there. He's paying a lot of money. He can have everything And then take those restrictions that you're considering had what you're holding back and what you're providing and look back at those use cases Those user stories and have a look to see if they are validated against it compare those Examples that you've come up already and see whether your API matches up to there. It's a really good example of Holding back on providing too much Capability if all you need to do is solve a couple of use cases So when I first started designing this talk, I put a tweet out there. I thought I was very novel I thought yeah, think of the users. Why doesn't anyone think of me when I'm creating this stuff? Expanding on all this frustration that I've got from all these people whose API's I've had to integrate with in the past Put that out there think of the users. I got this great idea Someone immediately pipes up and says oh, you're thinking of API UX and of course there's a website about it So if you go to API UX calm There's a really good blog there by Bruno Pedro, but one of the things that I found on there is the API hierarchy of needs So hopefully most of you if not some of you if none of you have heard of the Maslow's hierarchy of needs Basically, it's a ranked hierarchy of things that people want in order to be happy in life And in this example, it's how to be happy with an API So we have usability Can you use it if people can't use your stuff? They're not going to bother. They're gonna get Sweary they're gonna leave and use a competitor Functionality does it continue to work as you like and reliability does it always work the same way? Does it stand up? Does it always fall down or is it always available? Proficiency now I know it can I do cool things with it? Can I use it? Do I know it backwards or is it always changing and finally that creativity? What new novel things can I do with this stuff that this wonderful? Developer who's been to Chris holds talk has provided me So starting at the bottom usability That's not in the bathrooms here by the way Just in case you thought it looked familiar Usability if people can't use your software they will not use your software Unless they're paid a lot of money or unless that's the only thing they have as soon as a competitor Pops up with a more simple approach a more usable approach That uses jump ship Unless they've paid a lot of money to develop and lock themselves in with you They're over to the other side and you lose any future customers to that competitor So think about how you can make my life easier to use your service to use your library and key of that consistency If I've used your software before and you introduce a new feature Or if I've used a small part of your software before and there's another API that's been presented if they're not similar I need to start all over again. I need to start learning new things And as soon as I need to start learning new things I'm a lot less likely to want to try and jump in so if you can find ways in which you can improve that Consistency across your endpoints across the public methods of the stuff that you're putting out there Then by all means do that because that's going to make my life easier when it comes for me to start integrating a bit further into your stuff Look at style guides PHP has PSR is one and two and the soon-to-be brought out PSR 12. I think it is for PHP 7 Drupal's got your own code style guidelines Follow those because at the end of the day if I look at the way that you've created your software And I look at the way in which your software is laid out if I want to change that or if I want to understand it To see a language that I understand to see the way in which PHP is used underneath To see the way in which this rest service is presented to me If it's something I recognize and I'm familiar with then I'm a lot more likely to be at ease with it And for style guides in the code level anyway You've got tools like PHP code sniffer and for Drupal you've got coder I believe that can look into the the code style that you've got there and help enforce that when you have common attributes and functions getters and setters or a Crudway of accessing your underlying objects use the same words It's no good having get title on one object and get name on another Unless they mean specific different things such as a Salutation for one and the actual full name on the other you want to keep that terminology consistent Because as soon as I start using another kind of module that you put out there or another object that you put out there I'm going to be looking for that get name I'm going to be looking for those similar styles there Naming as well if you have a nice convention There's the old C style of actually prefixing stuff with the types. We don't need that anymore but certainly look at the ways in which that you can Name everything in a very consistent fashion something that falls into place error codes if I Have an error in one thing and I have the same kind of error in another if they don't have the same error that comes up to me. I'm never going to understand so in Rest in web services you've got the 400 error, which is catch all bad request and if something's not found You've got a 404 not found Which hopefully you all know But you can use a 400 in place of the 404 It's just as valid. It's just a lot less specific So if one place in your application Responds with that very specific. I haven't found anything and another comes across with something. That's a bit more a Bit more general. There's been a general error and it's your fault How am I as the person integrating gonna understand what you've put across and that kind of goes on to patterns so patterns are Existing established ways of solving similar problems across so hopefully most of you have heard of factory patterns There's observer patterns And all sorts of patterns that are out there they solve problems that you encounter day-to-day as your coding And if you use those people are more likely to be able to look at your software and understand exactly what you're trying to get at They can understand. Here's your solution Here's the problem and know exactly how you're approaching that In web services, we have RPC and we have rest different ways in which we can interact with stuff And if you look at the way that people apply these Patterns in a consistent way across not only your software, but across the whole software Ecosystem then you can find ways in which I know exactly what to do when I need to Create something in a web service a post or a puts to update it and so on So immediately we're again talking that consistency that same language with our users as we're putting stuff across And if you're interested in software patterns at all They're mostly laid out when it comes to the code level anyway in the gang of what's known as the gang of four there's a It's all laid out. There's all factory is put out there I forget the name of the authors, but have a look it's known up there and you can pick that through an Information hierarchy for your application is also important Understanding when you've created these objects how they relate to each other. So uber might have a Car to represent a taxi. They might have a person to represent the driver. They might have a passenger to represent a passenger but uber's Way of looking at the world might be more focused on the car for example Or on the driver then on the passenger Whereas the passenger or anyone who might be integrating something on behalf of a passenger would be more concerned about themselves So if you think about the ways in which people are going to be using your software The ways that they're more self-centered rather than you Apply those models to the way that people interact with your software Okay, so and An API where the car is the most important thing for you The passenger who's going to be paying you the money or who's going to be paying someone else to integrate with you Wants to think about themselves. So look at it from their point of view rather than imposing your structure on those people Nesting entities can be problematic if you go three four or five things deep Then all hell breaks loose when someone's trying to work with your stuff So if you have a car and a passenger and a wallet and a dollar Immediately you start getting more complex as you're representing these things with your interfaces And if you get this right if you get the cell this focusing on the user, right? Then it becomes a lot more intuitive for them because they're working with themselves and not necessarily with your cut your company focused way of doing things an abstraction Take those user stories. I was talking about reducing complexity and providing simplicity Abstraction is a great way of doing that if you need to know to book a taxi ride You need to find the car you need to tell the car to go somewhere And then you need to produce a fare that might be three API calls or three separate functions within your kit But a customer doesn't want to hit each Individual object each time to work through that process that very common use case so if you take those user stories and Work that out. What are they trying to do? How can I make a three-step process into one step process? So you can just have a book a ride function that hits those three things underneath, but that's provided that simplicity under That's provided the simplicity for the person who's integrating with you hide that complexity Because above all things what that actually lets you do is in the future You might have to add another call that says check that the car is available for example And that would be another thing that your customer might have to do just to get this common operation going But if you've abstracted it correctly if you've reduced the complexity down then you can make all these changes underneath You can change your entire underlying model without actually impacting the customer and breaking things for them Do the hard work so your users don't have to The more simple that you provide stuff Look at stripe. Look how easy it is to take payments with stripe That's easier it is the more likely you are to get traction the more like you are to get users the less likely you are to have Someone's swearing at you in the middle of the night and from that you get simplicity It is the best result of abstraction. It's the the if you can take these complex blocks inside Take them into smaller blocks and allow some to build something with that It'll be more straightforward more use and With a smaller footprint with fewer places to interact with Any faults that come up any problems that a customer has or any problems that software has using your stuff It'll be a lot easier to narrow down exactly where that's happening if they're hitting your API 345 times just to get one thing done That's 345 places that you have to check to see if there's a problem if it's just one Then you've got a great place to start the downside of abstraction Is if you provide very specific use cases you can Make it more difficult to extend upon what you've written You might reduce the opportunities to be creative with your API If you've taken away the concept of a car from a customer and you've just given them the ride in general Then they wouldn't necessarily be able to Unknow locate the five best cars around and bring them in and create their own things from more basic building blocks so finding a way of Balancing that and that's not an answer. I have for you today But finding a way in which you can find that nice balance of abstraction versus extensibility is going to be quite important Think about how people will build upon that your use cases might cover up exactly what the application is underneath But find ways in which you can understand how someone's going to be using your software Are they going to be using clients? Are they going to be using your API directly? Are they going to be using your objects in a very constrained fashion or in that more abstracted way that you put out there? And that will help guide you in terms of finding that balance those ways in which you can find the right Kind of level of which you can abstract Restrict it as required. So in web services, you can use ACLs access control layers in in your code public protected private and While there's a discussion between protected and private Think about how What you want to expose Anything you make public in one version of your software If someone's built on top of that then if you retract that if you take that back, you've immediately broken their stuff So the less stuff you put out there to begin with The easier life is going to be for your customers You're going to be a lot less likely to break stuff and also you have a responsibility when you've made something public and publish that and People have built stuff on that you have a responsibility to not break their stuff So yeah, take care and it is hard to retract the public access stuff and patterns help Finding ways in which you provide just to get method for a factory as opposed to all the underlying building blocks That provides a nice simple way an abstracted way a Focused way of getting things out without exposing the complexities of building objects to your customers So on to the second level of the hierarchy function out well and the third functionality and reliability Yes, I do do color I've lumped these two together because while functionality is very important. Does it do the thing? It's supposed to reliability is equally as important. Does it continually do the thing? It's supposed to does it fall over does it pick itself back up again? Or is it reliably there time and time again? So how can we think about the ways in which we can enforce this and? discover whether we're reliable or not testing how many of you use simple test or PHP units or any of those unit testing frameworks a few of you How many do PHP spec? How many people do? Behavioral stuff so be hacked and BDD or any of those tools around there So finding the right approach For your code is pretty vital in getting all this stuff down unit testing Tells you whether it works the way you designed it Behavioral testing and functional testing to an extent tell you whether it works the way the customer expects that you built it so because behavioral works on the level of as a customer. I want to do this then I do that and Works on their behalf You can actually look at it from their point of view in a very straightforward fashion versus the unit test Which just says does it work the way I designed it? If you can build all these tools into your build release process if you're using continuous integration or continuous Deployments and get those warning on you then anything that you break with any new version of your code can be immediately picked up You can easily refactor underneath You can easily stop yourself from breaking your customers code, which at the end of the day is what you're after If you stop it dead or if you just make it warn while you're building stuff And you make it a roadblock or just a road bump on the way to production Then at least you're there you're forewarned you're forearmed as to when you're going to release a break Think about how you can take those tests and point them at your production servers If you've got an application out there providing a web service If you're the first person to find out whether you've broken something whether something's fallen down and your customers never noticed That's the best thing you can do if you're out there ahead of them before they put that call into customer service you're on a winner if You're doing web services think about recording everything that goes into your web service and comes back out Every request that pops up in the access log anything that hits your engine X your Apache And then at future dates if there's been a fault when that goes in Take those logs come back you can replay it against a production like system and recreate it there and then And then finally regression testing I mean the number of times that I've refactored something and it's broken an Obscure use of my software too many times for a professional myself, but it happens The more unit testing you have in there the more automated testing the more automated systems you have in there The less likely you are to to break stuff the more likely you are to be able to safely refactor as we go through metrics Do we all use Google Analytics? Yeah, how many people use metrics in their software itself as opposed to seeing a visit Count events that go through a few So for those who don't metrics tell you What is happening? So you can say every time an event comes up or in Drupal you might have a hook in there Using the symphony event system anything like that. You can say on that. I'm going to count one This API got hit the once or this API produced this error code X many times and you can store that for a posterity and you can watch to see exactly what happens If you've got high volumes of traffic going to your stuff and you're putting that into the right place You can you can chart it you can put graphs up that show you exactly how over time Your API has been used where any faults might happen. You can correlate that against any events that might have occurred If you take those status codes, you can see elevated 500 internal server errors and catch that before our cut the customers really start to or tie that up against the release You've just done If you calibrate that with normal running if you know how many roughly you get per day Request that come in and that suddenly falls off a cliff Then you can set up alerts through systems like Nagios or Zenos and actually get told that you know We've only had three visits to our page not a hundred visits to our page in the past day What's going on here and get out ahead of it? It gives you that insight into running code and if you need to debug something in production If you need to understand whether it gets us something's gotten as far as you like You can't put any profiling in because you're afraid that it's going to be too much or abused The metrics give you a nice point of saying well if I count everything that goes into this function And I count everything that goes out do those numbers match up At data, so if we use graphite to store the stuff and stats D to actually transport it across the network So we raise metrics on each of our servers pass it into this stats D package and it gets sent across stored and we can render it Runscope also as an example of a service that you can use will do this metric stuff for you as well You put your hooks in and it just monitors as you go away. It'll raise alerts and so on The end result of all those make metrics. This is our operations wall this was Mostly in use while we're doing our streaming platform pulling all of Twitter through and one of the interesting things is on one of Those charts during the World Cup final a couple of years ago. We could see every single goal scored against Brazil Because we are counting every tweet that was going through the platform So every time Brazil's every time Germany scored Peak in there and you can see real-time events going through Also, we have up there We've got a little blue light that flashes every time a bad alert comes through and we had all the ops sitting down below that blue Like they so they knew exactly what it was going on Later on we added lights in the background and gave a bit of electronics challenge to our ops to make the lights go Red or green depending on what the state of the platform is But yeah at a push you can see the metrics charted there You can understand exactly what's going on You can see one part of your pipeline if that's what you have stuff going through and whether it appears in another part and so on the other part of Understanding what's happening is logging and that tells you what happened So metrics says exactly right now Something's down something's up and so on logging gives you a chance to understand what happened why those numbers have changed and Helping you debug program production fault. So how many people have debug stuff by putting print statements in right? Yeah It works It's effective But a slightly more effective way and one that you can leave in in production is using logging Whether that's putting it into error log and just firing that into assist the sys log of the platform or whether you're using a I'm gonna get the number wrong here But one of the PSR compliant logging platforms like monologue Whatever you're doing there if you're recording things that happen Then as soon as your metrics fall off a cliff or as soon as your customer has an error You can look back and you can see in English or whatever language you speak You can see exactly what's gone on and you can understand the points at which things have failed and If you are providing error messages to a customer based off your service It's a really good idea if you don't know or you can't reveal the cause of a problem You know the number of times when oh we couldn't connect to the database, but we don't want our customers to know that An internal server error occurred. Please try again if you provide them with a reference Say take MD5 and hash the time that it occurred so you got a pseudo random set of Letters and numbers if you can give them that code you can then cross-reference that against your logging as you go on so you understand that this request Produce this error gave this code and here's what the real message is in our logs But we'll hide that from our our customers. You don't need to know They provide that insight into running applications so that you don't have to go in there and throw your prints all over the place in prod just for one minute of understanding what's going wrong and If you build that into your libraries if you build that into your modules or your plugins and so on you can actually allow your customers to inject Or the people using your software to inject a logger and have an understanding of what's going on in the first place Right, so if you've got a really complicated piece of kit and want to provide some real-time Understanding of what's going on in there putting in log lines and allowing someone to either raise the log level or put a logger in Will allow them to see what's going on as it comes out of the logger Versioning I could do a whole talk on versioning. I'm not going to it's okay But it's very important that you start off planning to have a version two or a version three of the stuff you write If you're writing web services, even if this is a throwaway thing that you're never going to change you are going to change it So figure out a way that you're going to version it for your customers Even if it's a simple slash v1 slash v2 at the beginning of your URLs for a service It's very important that you have a strategy to do this because the pain of moving people off of old versions is immense I mean we've seen that we're looking to hit We're looking to hit Terminal velocity or or whatever that the phrase that Dries used this morning on Drupal 8 But the amount of effort that it took to get to that point the amount of effort it took for people to move from PHP 4 to PHP 5 was incredible And every time that you don't plan for those version changes, you're gonna have to go through that pain yourself If you're doing stuff in code look at semantic versioning That's a case where you've got major Minor and patch as part of your numbers so 3.2.1 Every time a major version happens It's a total rewrite of what you've done every time a minor version happens You've introduced some breaking changes, but you're pretty much consistent every time a patch happens It's all backwards compatible with everything that starts with the same major and minor numbers But it lets you know that there's a newer version of the software out there and you can manage that kind of dependency I think there's a talk later on using composer with Drupal and composers a great example where semantic versioning really helps the PHP ecosystem Understand what a breaking change is understand how customers are going to upgrade and How you're going to tell them how they need to upgrade if you deprecate a piece of code if you say this is going away Make sure you take it away. Don't just leave it there Make sure that you have that stick of removing functionality So that they get moved on to newer versions rather than become complacent with the things you put in front of there Be very clear what a breaking change is Be very clear that if you add another field to an API response, that's not a breaking change We had one customer at one point was taking our API responses and just turning them into SQL inject Insert statements. So every field that we provided they'd say that's the column and then they take a value as well Which is great until we started adding a new field and suddenly there was another a new field appearing in their perfectly automated System that doesn't exist in their database We didn't think it was a breaking change because in PHP lands No one really cares if there's extra information in your JSON response But they were very sensitive to it because they needed the extra column as it goes in so be upfront with customers and people who use your stuff as to what a breaking change is from your point of view and Tell them upfront how long you're going to support an API version if you have version 2 there and Someone spent a lot of money integrating with it They want to know that they're not going to have to spend that again in six months time because you've discontinued support for that Especially if you're dealing with enterprise customers They want to know that the money that they've spent on all their developers to figure out how to include your stuff in theirs is Well spent and won't be spent again in three six twelve months time So be upfront as to how long you're going to support something and then when that time's over remove it deprecate it get rid of it Upfront figure out how you're going to communicate that information with your customers as well How are you going to open those lines of communication with them and tell them that these changes are coming that they've happened that they've missed the boat? And and along with those lines of communication Tell them how to get back in touch with you. You know, it's one thing having a mailing list It says every time I've got a product update send the stuff out But how do they get in touch with you report bugs? How do they give you product? Improvement information and ideas to get in touch how that how do they give you praise? How do they swear at you give them a chance to get back to you the more likely? The more that you respond to them as they come in the more likely they are to stick with you and forgive you your faults When you're giving that information about errors that occur Give them a reason if it's not a problem for them to know then just be open people appreciate honesty and openness and Tell them if they can fix something if you're saying it's your fault you haven't filled out this form correctly for example How many times have we seen forms not filled out correctly and no one said what the problem is? It's the same with our APIs if someone hasn't provided a name in an API call Tell them that don't just say you haven't used it right move along tell them how they can fix stuff Use appropriate language. They might be swearing at you. Don't swear at them The number of times I've seen sweary error messages is a bit too scary When you use error codes instead of just throughout how many people use my SQL and have seen earno 150 and Wonder what the hell is that? if they just told you in Very simple terms that Table is missing It's still something if you use some words and say table dot missing or anything like that It's a lot more intuitive and it's still just as predictable as a number as it comes out So think about ways and instead of just providing a number provides that information. That's human readable as you go through and Provide a glossary for that if you know all the error stuff that you come up with Give a lookup table for that something that someone can refer to in documentation as you go through Because the number of times I've had to look up earno 150 is a bit too many So proficiency, how can we get better with the use of the software? How can our customers and our users understand that a bit better and make things that are cool and that sing? If we're doing web web services providing a client for our customers as opposed to just giving them the API raw That's a very good start The downside of that is your product your service extends into their code You're no longer responsible just for what happens at Apache You're responsible for what happens on their side of the fence But it gives them an immediate way. They don't have to understand curl They don't have to understand streams or anything like that. They can just use the software that you provide them directly So that's the best way in which you can get people up and running quickly is if you can provide them with software that they Understand that lives there that they can update that they can Update without breaking because of our versioning then that's the first foothold that they can get in there that makes their life a Hell of a lot easier. It is the edge of your product And as I said with versioning treat it exactly the same way as your web API if you're doing that every time you put out a Change to your API put out a new version of your clients Update it show them where to find those updates Use your versioning as we go on and use the native standards again PSR is one and two or the Drupal code standards are perfect for this because they can delve in and do any fault Detection that they like if they understand the code I know we turn around and we look at our colleagues and we say well He doesn't write great code, but they're turning around and pointing us and saying he doesn't write great code If you stick to those code standards and if you provide those and push those out to your customers They're a lot more likely to to accept the code that you've written Documentation I like to say there is no such thing as self documenting code And that's doubly so if the code is not available to you if you can't see the code What's the point? so Use your documentation skills use your Drupal site put those APIs out there and describe that in plain English and as Accurately and as up-to-date as you can put those things out there Give working examples. How do you use your clients? How do you use your APIs? Anything that helps promote understanding of what you do and the reasoning behind what you've done Cross-link from your code If you're providing a public API from your software if you can just link through to the documentation from your from your software itself Then that immediately provides your colleagues a way of understanding what you've done And it immediately lets them know that there's a document that they need to update as they go through and make changes to what you've done As with everything, you know with with Drupal with WordPress with everything like that We have manuals and quick start guides and cookbooks and all this overhead, but it's very valuable You know, we wouldn't know Drupal We wouldn't know PHP so well if all these sites weren't available if all this documentation wasn't written for us And we can take that one step further So Documentation one of the pains of it is keeping it up-to-date if we can move it closer to our code If we can update it at the same time as we make changes to our code We're proactively lazy as developers, right? We see something that we can automate. We see something that's boring And if we can automate it, we'll do that make it happen and then we never need to touch that problem again We never need to touch that challenge again. So look at ways in which you can use your document blocks Java doc or PHP doc There's the Drupal current standard as I've mentioned and so on Look at ways of filling that out and then just run PHP documenter over it Or I think and anyone can correct me if I'm wrong There's an API document an API documentation generator for Drupal modules That will allow you to put that out there if you all just keep it close to the code Every time you change the code and update the documentation while you're there and then and you understand what you've done That'll make your life a hell of a lot easier Using those annotations that are defined there. You can actually generate interactive documentation So we build a system that used IO docs from Mashry But swagger anything that uses ram or anything like that and if you put those annotations in your code run a Documenter over it. Not only are you saving yourself the hassle of changing in multiple places, but Certainly with swagger and IO docs you provide a little console that allows someone to put their authentication details in Hit go and just play with it live And all you've had to do is change a couple of lines of text in your code itself Make that part of the build process and every time you put a new version of something out there It gets published to another place and you're laughing And I was talking about feedback earlier, but to find those channels of communication Tell people where the official places to talk to you to get in touch and to talk to other users of the stuff that you've done That provides a really great support mechanism for people not only from you, but from the community at large The number of forums that we as developers have to use to understand what's going on and stack overflow and Any applications that we use that have forums to help us get results. We just stick with it a bit longer We fall into communities as we're all here in community We understand things a bit better and help those around us understand those if we tell people where to go to find that Understanding and to find that support. That's a really great start of getting people up and running And respond gracefully in a tentatively again. I said earlier. Don't swear don't swear If someone says there's a problem nod Understand what the problem is they might be entirely wrong, but instead of just saying it's all your fault You're an idiot turn around explain it respond with grace and Kindness because you used to be that person long ago before you stepped onto IRC and became cynical Think of all the times that those people of that the people who've responded with Either nothing silence or really sarky comments how that damage your confidence. Don't be that person and Because of that you can learn from the users and because of that you can learn with them and you can keep them going on They've built that trust in that rapport with them The final piece of the hierarchy you'll be glad to know is creativity now When I approach the hierarchy when I approach this as a concept I Kind of ran out of ideas. I I am a kind of creative person, but I couldn't come up with a great title for this Creativity is all about serendipity If you provide to the stuff there if you provide all the things we talked about the reliability the documentation Anything that provides understanding and helps people learn as you go through Eventually they're gonna be the ones that turn around and say if I put this with that then I can get Wow right So providing all of these things that I've talked about so far leads you to the path of people Building a friend search on top of Spotify location information. I'm sure Spotify probably want to do that now, but Previously they just wanted to provide music But this whole kind of ecosystem when you've got a nice open API a well documented and supported piece Can spring up around you and suddenly people be doing stuff with your software that you never realized they could do You didn't design it for that They weren't in your use cases or user stories, but because you put all these structures and all these versions and all this Cookbooks and stuff in place the flock around it and start building on top of that. I've talked about best practice I've talked about a lot of stuff today, right? I've talked about writing manuals and cookbooks and everything like that And there's a lot of stuff on top of that, but ultimately be pragmatic You only have so many hours in the day So choose your battles wisely Think of what provides you with the best the most impact as you go through It's good. You know, we can't just be polishing stuff For the rest of our lives. We've got to put it out there as someone said not too long ago Great is the enemy of good Right, if you're a perfectionist and you're waiting until it's perfect It'll never get out there someone beats you to market or you never update your stuff as you go through It can promote technical debt if you find those shortcuts But ultimately at the end of the day if you manage those processes and understand the debt you've created Then you're in a better place for that Find your balance rest doesn't actually cover everything that we do RPC Remote procedure calls doesn't cover every use case that we have So find a way in which you can fit concepts together in a consistent fashion so that you can make those Shortcuts but in ways that people understand as you go through be realistic Get that stuff out there get people understanding it and playing with it sooner rather than later Because that way you can start learning from them as we talked about earlier If you iterate and if you start small you start with MVP minimum viable products put it out there Get people using it and you've got that versioning in place You can improve and improve and improve and you can show that there's something there behind everything you've done But above all going over this Going over all these best practices and being pragmatic and not dogmatic The one thing that you should always bring to what you do and put out there is pride Be your software's biggest advocate You know not at the point of putting everyone down, but be enthusiastic be your own cheerleader. We're engineers We don't really do extra version, right? We're not really the people well some of us aren't the people who stand up here and talk But at the end of the day if we're not supportive and talk up our own stuff then No one's gonna use it. So on that Thank you very much. Have you got any questions? lunch has gone down really well So The sprints are going on on Friday. So there's a couple of extra bits of information up on the screen there Also I'd be really interested in finding out what you thought If the lack of questions was because I told you everything that you knew already then that's perfect because preaching to the converted is very effective But just give me a bit of information back there And if you want to get in touch with me then find me on Twitter and LinkedIn and an email and stuff. Don't be a stranger. Thanks