Welcome. To Google next and welcome. To this talk on. Designing. Quality api's. I'm. Glad to see a reasonably good turnout. I did want to give a presentation, here in in, San, Francisco, and. I was scheduled, in a back room at. The same time as the keynote presentation. With some reasonably. Famous speaker. I can't remember who it was and. When. It came time to start the. Session there. Was exactly one person in the audience sitting, in the front row and. I was just sort of considering, what to do at this point when. Some fellow wandered in through. The back door and it, was fairly obvious from, the way he was behaving that he was completely lost he didn't know where he was so, I gave him an extremely warm welcome, and thanked, him for showing, up to my to, my session so. Of course at this point this poor fellows stuck I've sort of cut off his line of retreat. So. Anyway the three of us sat in the front row and just sort of chit chatted and, for an hour so I'm very very happy that so, many of you have turned. Up for this talk. So. I assume you're here because you're interested in api's and if you're interested in API you'll know that there's. Lots of controversy around API s and there's lots of conflicting, advice on. What to do, my. Experience is when that happens it's, often the case that people aren't really disagreeing, about technology, the reason that they disagree is that, they, come. To the problem with, with. Different ideas and different values different, they have different objectives they're, trying to solve different problems and, so. Since. They're actually, trying to solve different problems they tend to. Disagree. About the solutions. So. I. Thought I'd take a moment to. Talk about some of the different things that people are actually, trying to achieve, when. They approach, the problem of developing, an API. This. Is a picture of Richard Hamming you, probably heard of Richard Hamming is a famous, person and in. Computer circles he was a sort, of mathematician, and scientist of the, 20th century's, famous for Hamming codes which, are error. Correction. And detection. Codes, which are actually still use today they used in RAM memory and they used in, wireless. Protocols. One, of the things that Hamming was famous for in addition to having windows Hamming, distance, I mean codes and, he was famous, for a series of lectures that he gave and you can find those lectures on the internet now you've this versions, on YouTube as well as written, versions, and one. Of the most famous is called you and your research. Which. Is his advice to. Researchers. On how to maximize. Their impact and, manage their careers and hamming. Himself says that although he's his. Experiences, from research his. Advice is useful, in in, different kind of domains and so. Having makes them both some important points some useful points if, you, really want to have an impact and then, you should make sure that you're working on problems, are really important, problems in your field if you're not working on the important problems it's unlikely that you'll do, important. Work. Another. Point that he makes and in fact this is a great talk if you're not familiar with Hemmings lecture, then you should go and spend, some time looking at it in fact the truth is if you only had one hour to spend you, probably do better to spend it listening, to Hamming than listening to me but I'm gonna assume that you have two hours to spend so, you're gonna spend one hour listening to me and then when. Are listening, to Hamming and the. Other thing that having talks about is this idea of having an attack on a problem, and for him an attack is kind, of a possible. Approach that. Might lead to a solution to the problem or at least make, a dent, in. The problem and in fact he says that there. Are the three greatest problems in physics for problems that he never worked on and really nobody else ever worked on during his career and those three problems were time. Travel, teleportation, and. Anti-gravity and it's, not that those weren't, problems, who's for. Which a solution would it would have had an impact it would have actually changed the world and it would have given you a reputation, that would have lasted centuries along, with your with your Nobel Prize, but.
The Problem is nobody has a faintest, idea how to attack those problems how to approach those problems and therefore it's, a waste of time I'm. Sort of working on them so. Good problems. Have. The characteristic. That they, are really important. In. Their impact and your some idea how to tackle them. So. If we bring this back to the world of api's. One. Very common way to think about an API and the purpose of an API is that, it's a way the two pieces of software can communicate, across the network I have a client and a server the. Client needs to get at data, or to invoke actions, on the server and we, want the communication, to be fast secure and easy, to program so, it seems like many. People come at api's with that as. Sort of the problem, definition and. That's. Actually not at. Least by hemmings definition, an important problem in our field that, doesn't mean that it's not important, you, know that could be very I've, worked on many. Projects. Where. Those were, you, know solving that problem. Was, important but this is actually a solved, problem there, are several good technologies. For. Doing this and. You just have to pick one if, you think that this is what, this. Is what your primary problem is. Here. Are some different goals that you might have, if. You're defining an API and these, are important, problems, in our field and these are unsolved. Problems. So. One important problem is that software, is just basically hard to change, and. Every. Enterprise that I've ever worked in or every Enterprise that I've had contact, with and worked and worked, alongside with, which is a much larger number and, has. Had the problem that they're essentially prisoners over their existing, software you. Know you build up and then unless you're in the first few months of a startup you have a legacy of existing software, and. It's, never what you want it's. Never what you want for your business needs, the.
The. Business scenarios, change the business needs to change and it's never really what you want from a technical point of view either you know once you've done something you always immediately. Learn how you could have done it better and. So, you but but you're stuck with it and it's difficult to change is difficult to change because it's complicated, and it's difficult to change because in almost all the systems that we have they're, permeated. With assumptions we have difficulty. Containing. The assumptions, that we make whether those are technical assumptions. About which databases, are which technologies, are which implementation, languages, we use or, whether. Those are business. Assumptions. About what actually this. Cheerios are that the system has to support. Which is also something that's changes. Software. Is very also very, hard to. Integrate, and. Integration. Is a huge issue especially in, well you know in all of the enterprises. That I have worked, in. Every. Almost, all the enterprises that I've worked with of some kind of initiative, to get a 360, degree, view of the of the, problem which, is basically, how do i integrate all. The information, that i have about a customer, or they're. Trying to integrate, the total experience there are many points of contact with a customer and they're trying to integrate. Those things together and, many. Of you will have traveled here to, the conference when you made your booking that's, a big integration, app dealing, with hotel reservations. Your credit card. You, know your flight reservations. And things like that and when you go back and do your expense report, assuming. The use of a reasonably. Modern sort of expense report tool which I'm sure most of you have that's. Another big integration, app that's integrating, your credit card bills. If. It's a nice modern application, your flight, receipt. And your hotel receipt, will already be known in your expense report and associated, with your trip that kind of thing so a big a big kind of integration app so, a huge amount of the development, that, I see. Is. In. Fact integration. Development, we build up these little sort of silos and then we realize that there's a large amount of value if, we can if we can integrate those silos and. Software's. Hard to integrate often. Because basic KPIs are. Not available so, it becomes it's difficult when you can't get at the data that you want you. Want to do and also because it's an N squared problem. Every. System has its own unique API so, if you try to do an integration thing you get to learn. You. Get you get to learn the api's of all of the systems, that you're trying to integrate I. Believe. That. Some styles of API. Go. Beyond, the. First problem, they go beyond, simply. Efficient. Easy to program. Communications. Between two distributed. Components. And they, offer a. Second attack on, those, two major problems because. There are other major problems in software like software quality, is. A huge problem but I don't have an attack on that one so. I left that off my list but I think API is providing. An attack on those two major problems. There. Are two dominant. Styles, of API. One. Is the NTU entity oriented, style sometimes, called rest I'll come back to that word in a minute and, in that style the client, code, manipulates. The entities, that, are exposed by the. Server and, the. Behaviors, of the system are hidden behind those entities what, I deal with is the entities themselves I can create entities I can update entities, I can relate entities to each other. What. The system actually does is a side effect of those entity. Based. Sort. Of operations, and. An older-model. Is the, procedure oriented, model, the sort of RPC model, and that one, is the perfect inverse, in that, one what. I. What. I interface, with is the procedures, that you, provide, and, the, entities, that those procedures are talking about are hidden behind the procedures, so, one puts the entities in front of the behaviors the, other one puts the behaviors in front of the entities there are inverses, of each other. Here's. My kind of stylized. Thing. And actually you probably annoyed at this chart I'm a little annoyed at this chart because it's. Trying to make a point which I actually believe is true and and the point that is trying to make is that in. Procedure. In the procedure oriented, style typically. What you end up with is a very large number, of these procedures, that. You have to master so, there's a lot of these a lot of these basic, procedures. Or functions that you call. That. That you learn a long list of the. Entity, oriented, style has more structure and the problem with this chart is that it's not really it's not really balanced, on each side the procedures that I'm showing actually, imply a number, of different entities there's the dog there's the owner of the dog there's the veterinary.
Surgeon. The. Deals, with the health of the dough of, the dog so if this were really a balanced, one I would have multiple entities on the left hand side. But. The point that is trying to make is that there's much more structure, on the, left hand side the left hand side is like an ER diagram an entity relationship, diagram, I understand. What the basic entities are I understand. The relationships, between them but, the actual methods that I call are very limited and they're always the same. In. The procedure the procedure oriented style is very similar to learning the libraries of a programming language and I think this is one of the reasons why RPC has been parentally, popular. With programmers, because, it's very familiar you. Learn a programming language you learn the libraries, of the programming language and learning. Distributed. API that. Is written in the RPC style, is just like learning another library it's not really very very, different from that but, one of the characteristics is all of those api's, are different. The. Entity, oriented, style is much, more similar to. Learning to use a database, so. One of the characteristics is if you use whatever. Your favorite database is my sequel or Postgres or Oracle, or whatever. It is a. Fundamental. Characteristic is. That there is only one API it doesn't matter how many databases. You have the. Database management system, that hosts that database defines, a single API that's used for all, of them so. You only ever learn one API now when you go from database, to database you. Have to learn the schema of that, of. That database you have to learn the tables and what. Are the tables and then you have you learn what are the columns in that table or if. You're using my sequel database the terminology, changes a little bit but the concepts don't change very. Radically, so. The entity oriented. Approach. Has this very interesting characteristic. Of of, solving, the N squared, problem. Instead. Of having an individual, API for each system I have, one universal. API this. Used with all the systems and. I. Give this talk well. I practiced, this talk I'm not actually very. It's. Not very common for me to practice talks but Google Google wants us to do the best that we can for you guys so I encouraged to practice this talk and when I give this talk internally, somebody said are you really telling me that my API, should just show issue just be a view onto my database and the. Answer is no that's not what I'm saying. What. You actually store in your database is probably more complicated you, may have multiple tables for, each entity you may not even have tables for your entity your entities may be assembled. From information that you get from other services, so it's not about taking your database. Schema, and just exposing, it as your API but. It is about using the same kind of concepts, the same conceptual model, for, an, API that. You see used for a database. Um. So. If. We're going to take these important problems it was there our problems was it's hard to change and, it's hard to integrate. Some. Of the characteristics, from API is especially, the entity oriented, API is that will help us here is one is having a uniform API across all applications. That. Helps with our N squared problem, another, one is having a uniform model for relationships I'll talk a little bit more about why relationships, are so important in this and then the third one is staying free, of implementation, assumptions, so, how do we get that from. From. This kind of entity oriented API I said it come back to the rest term REST, API is, actually a little bit of an oxymoron because. The. One of the primary rules of rest is. What. Was rest ret rest was rest, was one man's attempt, to write. Down the, architectural, principles, that. Underpinned, the, HTTP, web so. It's really a description of the architectural. Style are the architectural, principles of the HTTP web and one, of those principles is, uniform. Interface which means that it really only is one, interface, so, when, we talk about a REST API there's only one important, REST API in, the world and that's HTTP. So. When we talk about REST API is what we're really talking about is how do we just use HTTP. Just use it just be exactly as it is and apply, it to the domain of API, is really. What we're saying is don't, leer concepts on top of HTTP, just use it as is it is the univer Universal API. Unfortunately. HTTP. Has some gaps here HTTP. Actually tell you how to do crud. In. A nice way, HTTP. Does not tell you how to do query for example and query turns out to be very important for almost. All API s and. Neither does it tell you how to do versioning. So. There is some amount of invention, required, beyond.
The. Sort of universal, API, that's provided to us by HTTP. And how. Do you actually leverage, this uniform, API this HTTP, API well, again it's a lot like it's, a lot like what you would do with a database the first thing you have to do is you have to define a few well-known URLs, you know for example slash customer slash account slash orders which, is very analogous to defining what the tables are if I'm defining a database schema and then, I have to define the actual resource schema which is very analogous, to defining what are the columns. For. Each one of those entities and, then, the rest of the problem is don't mess up the basics so, when we have to start adding query and adding versioning, and things, like that do. It in a way that's compatible. With this standard, API that we want to. That. We want to show and, so. Here's, something that's very typical so here's kind of simplified version, and. If, you've worked at all in sort of you know HTTP, Jason api's, I, shouldn't think is very much here that's not familiar, to you, and but, the thing that I'm highlighting is this ID :. One. Two three four five, and. When you do that you've. Already stepped. Outside. The. Uniform, interface, and, the, reason is that the uniform interface that we're trying to use the HTTP interface requires, URLs it doesn't require, simple. Numeric, IDs so if. I'm gonna write my U if I'm gonna write my identifiers, this way I'm. Going, to require. Extra. Information about my, about. My API I'm gonna have to describe, in the documentation, how you take one of those your IDs and, how, you transform. It into a, URL that can then be used in the API and this. Was unfortunate, because it, would have been just as easy to do that and. If. I done that instead. Then. Now I stay, within the Uniform API. I don't require you to have extra. Out-of-band, information. About my. API in. Order to use the. Universal. The universal API which is HTTP, so, very, small change but these, things. Sort. Of make a difference, when they're accumulated. Relationships. Are extremely, important relationships, are extremely important when you're designing a database and they're also extremely important. When you're designing a. An. API, one. Of the reasons is that. API. Is the. The, fundamental problem, in most integration. Projects, is creating. Relationships between, entities that are stored in different in, different. Applications, sometimes, I'm trying to get at function. Through. A particular, API but. In many of the you know the integration examples, that I gave earlier for, example your expense reports, or your travel, booking, are, all about relating entities to each other you. Know I'm taking. I'm. Taking this this. Flight along with this hotel reservation, and I'm looking to get I'm linking them all together with this trip ID. So, I'm relating. Entities in different systems, and. Relationships. Are a very, fundamental way about whether we think you know thinking about the world in terms of entities and relationships is. An idea that goes at least back to Plato and Aristotle I, put. Their pictures here just in case you come across them at the conference, and want. To talk to them a. Major. Obstacle and, identity. Depends on sorry, relationships, depend on identity, I cannot reason about a relationship, and less I can reason about identity, I can't, say john, loves Mary, unless I can reliably, identify, John and reliably. Identify. Mary, and so. One of the primary obstacles. To, these kind of relationship. Based integrations. Through, api's is, the. Struggle that we have with identity, and here. The universal, API, the HTTP. API makes a huge contribution, by. Defining the concept of a URI or. A URL, which, gives us the ability to. Across. All of our systems, write, identifiers. In, a way that's. Standard. And repeatable, and store, all. Of those kind of things. But. Again we. Tend to make mistakes here. So. Here's here's. What yours in a I'm. Particularly. Got. The wrong pointer here. So. Here focus on this last, line so this is a very typical way that, you'll see people writing, are attempting, to write.
Relationships. In, a, typical sort of JSON, API you. Know the right owner ID owner ideas are is the, field. That I've used to capture the owner and I. Give its numeric, identifier now, the problem with this is that this identifier, I need a lot of contextual, information I cannot just use the Uniform API to follow, this link because, I, need, contextual, information I need to know where. I plug this it which other systems, can I plug this value into and how do I plug that in in a way that creates a URL that I can then use. And. In, fact this. Breaks down in different ways I mean supposing I have different kinds of owners you know some owners are police dogs right so. Or. Rather police, dogs have a different kind of owner in that, case the owner of the dog might not be a person that might be the police department, or something like that so how do I know how, do I know to resolve this. Number. By, looking in in. The system of. Institutional. Owners as opposed to personal. Owners those kind of things and we could have avoided all of those problems, if. We'd simply written, it this way in other words owners the relationship, and give, a URL if the URLs in the same system you can like write it relatively, I can resolve a relative, URL knowing. Only, the standard specifications. You, know published by IETF. I don't have to know anything specific, about your, your. URLs, or your systems, to do that or if. This. Reference, is something in another system, then. I write the URL in. Its full form and you might think about how you do how do you do this kind of example with our PC with, our PC is probably even more complicated with our PC you have to take something like this and then you have to know amongst all of the, all. Of the remote procedures, that I could call which are the ones that will take something like this as. An argument. So. Is, that having a uniform a model for identities in Crete is extremely important and the simplest way to do that to leverage the. Universal, interface HTTP. Is make. Every every, idea you you, are l another. Thing you should do is not confuse, identity. With name so, thinking, about identity is very important, it's very important if you're going to make this things work so. Think careful about identity, and don't confuse identities, with names. So. What is the name, well. Here's a nice description of what names mean, in English going back to. 1597. This. Is Romeo, and Juliet you. All know the story right in fact this is one of the most famous passages in all of the of the English language, and. So Juliet Juliet, would have made a terrific API. Designer, she, was she, thinks very carefully, and very clearly. About. About. Concepts, now, what's she saying to Romeo here is that your name doesn't really matter your Dame does none does not say. Who you are and you can cast off your name if your name's not convenient you know doff, thy name Romeo. Which, is very different from your identity, right and so. Names are terrifically important things they, do have a place in api's many, well-designed, API, support. Names but they do not confuse, names, with. Identities. So. Here's here's an example here's. A good identity, this is a pretty good identity, this, is a very simple, it, doesn't matter. What. Kind of what, kind of resource it is no amount of change you, know this pet oh maybe maybe, there's a problem with this actually because something. That is a pet so. For example if I have a goat. This part of a herd that's. Really just part of my this. Was one of my possessions, and then, I take pity on one of these poor sick goats and take it into my house it became a pet something, changed here right so this actually might not be a pet might not be a very good identity. Because. It refers, to a characteristic, that might actually change, something, that was a pet might. Not. Be a pet if it's just put out in a field with the other and kind, of animals the important things about identities. Is that they're immutable, it isn't they're not based on some characteristic, that might change and I, see, lots of people trying to make, identities. That look like this and, it's very attractive right because this kind of @nz one two three four five nobody, can remember that but, so but you can remember that you know lassie was a dog if you remember the lassie story from the movie and lastly, there was a dog that belonged, to Joe kara Clough unfortunately.
Lassie. Was taken away by the Duke, of I forget whatever so. Not a very good identity, because lassie changed, ownership, in the in the movie um but, it is useful to have URLs like this because it's very useful to be able to look things up by name even, but you have to be aware that names can. Names. Can change and in, fact that brings us to query so one of the things that I warned you about is that it's you're basing basing, you basing, api's on HTTP. Is a very powerful technique, but there are gaps in in. HTTP. Particularly. Around how you deal, with query. And in fact this. URL which, is basically saying you know find the dog or. The pet called lassie that belongs to Joe Carroll Clough. Is. Really, can be rewritten this way it's really just a stylistic, difference but both of these are, queries, this is not a uri in the sense it was a uri of a search not the uri of a dog and. It's. More if you write the query if you write the URL this way it. Doesn't really change the meaning but it does make it a little bit more obvious that in fact. This. Is just the URL of a query it's not the URL of a particular, dog and it's not guarantee and because it's a query it's not guaranteed to give the same real same result twice. Let's. Talk about representation. So representation. In HTTP, is the word that is used to, mean the actual format, of the, resources if I do a get on a particular resource, what. I get back is the representation. And, jason, in the HTTP, world jason is the most common sort. Of language that we use for. For. Writing down those representations but. One of our design problems, as an API designer so, you know what should the Jason look like and there are lots of options. Um if, your, focus is the first focus that I talked about that your primary reason for building an API is, for, efficient communication, between two components on the network then, the kinds of things that you're going to focus on is you want things that are efficient you, want things that are easy to parse you want a good match for the programming language on each end you know those are going to be your sort of primary. Your. Primary values, if your, focus is. How. Do I make things easy, to integrate and how do I make things easy to change in, the future, your, focus is going to be different you're going to your focus is actually going to be independence, from technology, because you may want to anticipate different. Clients, of the same API that will show up at different points in history and. Resilience. To change is, much more important, to you than things like user, parsing and sometimes. These. Are in conflict so, you, may have to make up your mind what's important, to you and if. You're, working directly with the implementation teams, they have a lot of biases, and they will push for certain things they won't like homogeneous, collections, for example, they, want things that are easy to parse and especially, if you work tonight working in a typed language like Java or NGO or something like that it's. Easier to parse things it's, not impossible to parse things if you don't have this but it's easier to parse things if you know ahead of time what, the types will be so, don't give me a collection, that has a lot of different types of things in it you. Know I don't want, this. The famous sound, of music you know my favorite things raindrops, on roses and whiskers on kittens right, so those are all different, kinds of things don't put them all in the same collection because, I find that harder to parse. Close, to content don't tell me that. You don't know ahead of time what all the fields, are because. In. My parsing routines I really like to know what all the fields are going to be ahead of time so you, know you'll get these kind of things I'll show you what I mean by index collections, union types aren't popular don't give me don't. Give me a feel that's sometimes, a string and sometimes an object don't. Really like that makes it harder for me to parse so you get lots of these kind of constraints. Coming. From developers. Of things, that they don't really like as. An, API designer, if your goals are, the, big problems that I talked about I think you have to push back on some of these things some of these things are fine you. Know it's not always a good idea to have a single variable that sometimes a string and sometimes a number.
But. If it does make if you think it makes conceptual, sense then. Maybe you should put push back on the. Implementation, teams you've got specific constraints, yeah here's an example of what I mean by index, collection, bias, and. This is actually I copy the side of an old Facebook. API this may not be current but there's a Facebook API for listing, photographs. And. You can see the way the data is organized is actually, reasonably, complicated with, my pointer. What. Happens, is that the, the. Outer. Name, in, the JSON thing is actually the user ID and, then, the in earth stuff, is a set, of photographs, for that for. That user and then, we start with a second user here, and then, we have a block that's the list of photographs. For that user and. When. You design, Jason. This way, what. You're really saying is that you're, favoring, one particular, access pattern for the data you're. Assuming that the. Primary. Usage by the client, will, be that they'll want to access, the photographs, based. On the user ID if they wanted to access the photograph. Based. On creation time or something like that this is actually, not a very friendly data, structure, so. Within, this data structure. You've. Sort of, advantage. One set of, access. Patterns, and disadvantaged. Another, set which. Might. Be okay but it, might have been better to do something simpler like this flatten. The whole thing out so. If I'd flattened the whole thing out well first of all it's simpler because it's much flatter and what. I really did was I took these user IDs, and I, moved them into the block, this. Is going to be less. Convenient, to use if, my primary access method, is. Accessing. The data by user ID but. If I'm accessing it by some other criteria it's actually better, I actually. Prefer this. So I prefer the second form because. I'm. More open to change five. Different users that have different access patterns, I haven't penalized the second set of users because I optimized, my data representation. For the first set of users even, although the first set of programmers were probably pushing, me. To. Do something like this because they wanted something that was convenient to their access, pattern um. I. I'm. Very public-spirited so. And. I. Have, taken, the trouble and to, write down a set of possible. Rules I'm not claiming that these are the only rules that you can that you need to follow and if, you're going to use, HTTP, well, but. I tried to write down a set of rules that explain how, you can use JSON and perhaps, the most simple form possible. That. That. Might be helpful and the, reason I like it is it's more abstract it's, less. Is. Less geared, towards, one particular. Access. Pattern. So. Versioning, queries. Queries not dealt with by HTTP, neither is versioning, and versioning, is a very confusing. Topic, one. Reason is there's at least three meanings of versioning, and it's, very common, when you hear people talking about versioning. For. People to talk past each other because, they, are each thinking, about versioning a different way they're thinking, about a different aspect of versioning and you, sometimes find. People even getting themselves confused. About using the word versioning, in two different ways in the same sentence, and getting. Muddled so, one. Kind of versioning I have dubbed here, entity, versioning, which, says there. Are multiple versions so I have a particular kind of an entity I have a travel. Trip or something to stick with our previous example. And. I. Introduced, version 1 of travel trip and then that was successful, for a couple of years and then I had a major upgrade and we completely reworked our data model because, we reworked, our data model to accommodate, some more advanced scenarios, and the.
Old, Trips. And the new trips. Are. Different. So. Every, time I create is so so, I introduced, a version two of my system but, when I introduce version 2 I started. Creating version 2 trips so every trip is either a version one trip or a version to trip but but not both at the same time so there's a different set of entities so that's a very common thing that happens when. You make when. You make a major change to your data model, another. Kind. Of versioning is what I dub I have dubbed this is just a personal vocabulary, but I have dubbed format, versioning, and what, happened there was I introduced trips and I gave them one JSON representation and, then. I realized from feedback from my customers, they. Didn't like the names that I chose for the properties, or they. Didn't like the way that I organized, the jason maybe from the previous example, I'd organized it the first way and they really preferred I organized that the second way or the other way around so I decided, to introduce a version too but. The important thing is that each trip, can, be viewed either, as through the version one format, or the version 2 format, they're not they're not two different sets of tropes that the same trips that can be viewed in two different ways, the. Third kind of versioning, that you hear about is, where, you keep Prior revisions, of the same thing so if I have a document a Google Doc for example, and I keep changing my Google Doc I may, have a long revision, history, for. That. For. That thing and you. Use these in different in different places you know if you use entity versioning if you made a significant, structural change to your data model you, use format, version versioning. If you're, making small changes to the representation, of an individual, entities and you use this and use historical versioning, if you're doing things like creating. An audit trail and doing undo redo and they're all different. So. Having got clarity on that let's. Look at format versioning, because that's the one that I think people do most, commonly, with api's and, let's. Look at some of the mistakes, that they make so. I'm doing format, versioning, so one thing that you'll see people commonly doing is this. They, put a version number in. A URL that. They then use to, try to make. A link and that, doesn't. Really work well and the reason it doesn't work well is that. Just. Because I wanted version, 1 of Lassie does not mean that I, want version, 1 of lassies, owner. And in fact the may not even be a version let's see I asked for version two of lassie they. May not even be a version two of lassies owner owners, may only have a version one so. It's, not possible, for. The server to. Select, the. Version, to. Use in a link. So. What that means is you, have one or two choices either you don't put version numbers in links at all that's. One possibility. So that will solve the problem or. For. Each entity you. Need to provide a, URL, one, that does have the version number in it and one that doesn't and the one that does not have, the version number is the, one that you will use in links, and then. Customers. Or clients can. Transform, that into a URL that does have a version number if they want to select a particular version so, either of the strategies will work, but. What will not work is trying to use links, that have verse or have trying to use you URLs, of version IDs in them in.
Links. So. You might protest that, if I if I do this okay let's say I take all of this stuff out so I've taken all the version numbers, or version identifiers. Out of the URLs but then I've lost some information, well you can put it back if you like you, know invent, invent. A property instead for, my, spine just start working. In. Very, invent a property that tells you which version, number, you are which version, format, you're looking at when you're looking at this and if. You also want to give if you want to give out an ID and. Also. Tell me exactly which version or, which, version I'm looking at of the current one or the URL of the current version you can use something like this and these values actually. Probably, probably. Fit better with the style of HTTP, if we put these in headers but there's certainly no harm in having them in properties also a. Lot. Of what we're doing here is just not messing things up right we've, got this Universal API called. HTTP, we, know how to work it it works based on URLs, just. Follow. The pattern so as you're designing things, and you're, having to add things that are missing out of HTTP, do. It in a way that doesn't make it doesn't, mess up the basics of how a p5, HTTP, is actually, so. The right way of doing versioning, is every. Entity has a version free identity, URI you, can allow clients to use the version free identity, URI directly. By, having an accept version, header or, you. Can allow, them to transform the URL into a different URL that. Does. Have. The version identifier, in it if you do that then you're having to provide. Basically. A transformation. Algorithm, that's specific, to your API it's not a generic part of the protocol anymore. So. I'm. Gonna wrap up here and invite, you to ask, questions, but. My conclusion slide is decide. What you really care about if you care, primarily. In this particular, application. That, you're doing if you care primarily, about efficient communication, between tightly coupled components there. Are lots of great choices out there G RPC, is the. One that's favored by Google and it's a great choice if you, if you're if, what you're focused on is latency, and throughput and. Efficiency and. Ease. Of programming RPC. Does all those things very well if. You're. Aiming for something more abstract that. You're creating your API is because, you're primarily. Interested. In decoupling, systems, so, that they're more adaptable, to change in the future or, you're. Primarily, interested in creating api's that. Will enable, integration. Scenarios and actually one of the most important integration, scenarios which I failed. To mention earlier is, the, one when you're publishing an API to, your, partners or customers so. If you're if you're creating api's. That. Will be consumed only internally. Within, your own or you think will only be consumed, internally within, your own organization. It, may be that the top set, of concerns might be the ones that dominate. Your thinking if, you're creating, ap although, actually I would challenge that but you, know anyway, if. You, but but if you're creating api's that will be used by other people that will be consumed, by development, organizations, over which you have no control you can't, change you can't control. Their, the rhythm at which they change things you can't control the way in which they're the version, things and you, can anticipate. All the different ways in which they will access your data if that. Is what you're designing for my. Recommendation. Is don't, use an RPC. Model. Use, an entity oriented, model and in particular, use HTTP, JSON, as directly. And as simply, as possible requiring. As little as possible. Extra. Information about your your, specific, API that they cannot glean directly, from the internet standards. That's. My. That's. My talk. You.
2018-07-29