Creating Solid APIs
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 | 132 | |
| Author | ||
| License | CC Attribution - NonCommercial - 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/44890 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
00:00
Programmer (hardware)FrictionSoftware developerUniform resource locatorRootInformationAuthenticationCodeFile formatError messageOperations researchDependent and independent variablesParameter (computer programming)QuicksortBitCartesian coordinate systemVirtual machineWeb pageCodeProduct (business)File formatSoftware developerMultiplication signProgrammer (hardware)Interface (computing)Revision controlFormal languageObject (grammar)Exterior algebraFocus (optics)StapeldateiPoint (geometry)Uniform resource locatorAuthenticationRootWeb browserComputing platformDependent and independent variablesInformationArithmetic meanKey (cryptography)CASE <Informatik>Goodness of fitOperator (mathematics)Web 2.0Projective planeMagnetic stripe cardRight angleElectronic mailing listTheory of relativityError messageAxiom of choiceParameter (computer programming)User interfaceMilitary baseNumberMereologyFrictionToken ringOnline helpVariety (linguistics)Computer programmingDemo (music)Computer configurationStandard deviationSign (mathematics)Different (Kate Ryan album)Computer animation
08:43
CodeClient (computing)Gamma functionData structureLink (knot theory)Endliche ModelltheorieWeb pageCanonical ensembleLink (knot theory)Data structureSystem administratorData managementDependent and independent variablesProjective planeCASE <Informatik>InformationCodeClient (computing)Point (geometry)QuicksortDifferent (Kate Ryan album)Standard deviationBitAuthorizationUniform resource locatorBefehlsprozessorElectronic mailing listAxiom of choiceOcean currentMultiplicationBand matrixLatent heatArithmetic meanSoftware frameworkObject (grammar)PasswordType theoryOpen setSoftware developerNumbering schemeVariety (linguistics)Similarity (geometry)Data storage deviceParameter (computer programming)Descriptive statisticsInformation securityNumberLibrary (computing)Electric generatorComputer configurationCartesian coordinate systemFinite differenceWeb 2.0MehrplatzsystemRootFormal languageTimestampFile formatVirtual machineOnline helpAttribute grammarTheory of relativityInclusion mapRoutingComputer animation
17:19
Field (computer science)Dependent and independent variablesElectronic mailing listLink (knot theory)Cursor (computers)Digital filterOrder (biology)Error messagePersonal digital assistantComputer configurationAuthenticationEmailClient (computing)AuthorizationToken ringComputing platformNumbering schemeRevision controlIntegerCodeCore dumpPattern recognitionInstallation artPoint cloudGoogolStandard deviation2 (number)FrictionDefault (computer science)Library (computing)Projective planeComputing platformQuicksortServer (computing)Latent heatAuthenticationOpen setMathematical optimizationDifferent (Kate Ryan album)CodeNumberCommunications protocolEmailToken ringLogicService (economics)State of matterPoint (geometry)CASE <Informatik>Web browserInternet service providerBlogMultiplication signImplementationObject (grammar)FacebookSoftware testingParameter (computer programming)Error messageGroup actionMathematicsField (computer science)Limit (category theory)Slide ruleRevision controlReverse engineeringSet (mathematics)Client (computing)Pattern languageMagnetic stripe cardMereologyBitControl flowLink (knot theory)Interface (computing)Numbering schemeElectronic mailing listDependent and independent variablesSpeech synthesisTransformation (genetics)File formatMetadataInclusion mapAttribute grammarMiddlewareProcess (computing)outputPosition operatorVirtual machineTask (computing)RobotComputer configuration1 (number)Axiom of choicePhysical systemSubsetExpected valueVariety (linguistics)Software developerScheduling (computing)String (computer science)Electronic program guideCartesian coordinate systemHypermediaCategory of beingLoginOperator (mathematics)Goodness of fitPattern recognitionSource codeUniform resource locatorInformationIntegerHTTP cookieWeb pageUser interfaceCore dumpOnline helpView (database)Data structureFehlererkennungscodeMobile appResultantFunctional (mathematics)Computer programmingDataflowMobile WebWeb 2.0MassPower (physics)AuthorizationLipschitz-StetigkeitStandard deviationSoftware frameworkArithmetic progressionFormal languageFrictionData storage deviceChainingMusical ensembleSpecial unitary groupData dictionaryPerspective (visual)UsabilityInformation privacyCursor (computers)Integrated development environmentCloud computingProgramming languageComputer animation
Transcript: English(auto-generated)
00:07
Thank you. There are still some seats in the front of the room as well as on your right side, so feel free to move up. So this is my talk on how to create solid APIs.
00:21
Our applications are increasingly being used not by humans, but by other applications via their APIs. APIs are eating the world they say, but ironically APIs themselves are first always used by humans, by the other developers who are integrating with your product. So that means that your APIs must target not just the machines, but even more importantly humans as well.
00:48
So a bit of background about myself. I come from Estonia and up until about a month ago I was part of ThorGate, which is an Estonian product development agency working on variety of projects built with Python, Django and other related technologies.
01:05
And this talk was inspired by one of those projects where API had top priority from the very first day. The focus was basically on creating a platform for forestry data and other developers had to be able to integrate with that platform, fetch data, do all sorts of operations on it and
01:25
the entire UI also had to be implemented on top of publicly available APIs. And as most developers I had worked with APIs before and even created a few myself, but this project seemed to have higher demand, so it got me thinking
01:42
how should I approach this and what are the guidelines and best practices and tips and tricks for creating APIs that other developers would love to use. And this talk aims to share what I found. So let's begin with the definition of API. Usually API is defined as application programming interface,
02:04
but I think a better one might be application programmer interface. Because when you think about it, then APIs are really sort of user interfaces for other developers. So let's think about what makes those user interfaces good.
02:20
I think that good APIs need to have documentation that not just help, not just exists, but it's actually helpful. I think that standards should be used to help bring familiarity and enable other developers get started faster. And you should always make sure that the user has to deal with as little issues or friction as possible.
02:47
And this talk targets mostly web APIs, but much of what I'm talking about is also applicable to other projects and packages and even code bases in general.
03:00
So let's begin with documentation. It's too often overlooked. We don't really want to do this. It's not the fun part, right? At least when you're developing, but it becomes quite crucial when you're trying to make sense of something that was created by others. And documentation is also quite often the first point of contact that
03:22
people have with your API or your project. And that means that the first impression of the documentation might decide whether they will stick with what you're offering or just keep looking for alternatives and competitors. I do the same myself, for example, when I'm looking for a package to solve some common issue.
03:44
There are usually a variety of options available and the first impression of the readme and documentation is quite often that deciding factor on which one to use. And documentation definitely does take effort and I admit that I'm not too good at it myself either,
04:04
but that shouldn't mean that we shouldn't try. So if you only took a single thing from this talk, then let it be this. Put some effort into good documentation. So let's think about how to create those awesome documents.
04:24
I think documentation is a bit like sales pages for your API. It has to convince potential users that what you're offering is really the choice to go for. And the good news here is that your audience for those sales pages is other developers.
04:40
Which makes things easier because you already know the mindset that you're targeting. So what do I want to see in the documentation? One of the first things that I'm looking for usually is just how can I access it?
05:00
Is there some sign up required for a developer account? Do I need an API key to access it? And if that is the case, then it helps a lot if you provide some demo API keys right there in the documentation. This is for example what Stripe does. You go to the Stripe documentation and even without signing up you have those executable examples
05:26
which include the API key that is necessary for accessing the API. I also want to know what the root URL is for your API. It's even better if your API is browsable so I can take this URL,
05:42
paste it into the browser and just start looking around immediately. And finally, I also want to know what sort of authentication is used if any. Is it the OAuth 2? Is it token based? Just some generic info to get them started.
06:03
There are also a bit more mundane things to look out for, for example character encodings. In the Python world we're quite used to Unicode and UTF-8 these days, but developers from other languages or other practices might not be that used to do it. So it always helps to point out these things.
06:27
The same goes for example for date and time formats. It's always a good idea to use CSO 8601 for example, but it's not immediately obvious and you still should point out some specific examples on what the date-time
06:45
what the return date-time looks like. I also want to know about how pagination and versioning and other features work. Is it cursor based pagination? Is it page number based?
07:02
Do I need to send the version with every API request and so on? And listing common errors that I might encounter is also very helpful. Stuff like what happens if I'm missing an authentication token or what happens if I provide invalid
07:20
authentication token. This enables me to just come to the documentation and search for the error message and find out very quickly how do I need to address the problem. And last but certainly not least I want to see some code that I can
07:40
copy based for example and just get started really quickly because it always gives us this warm fuzzy feeling when we have something that actually works. Your API probably also has a bunch of endpoints. For each of those I'd like to see the URL of the endpoint as well as what operations can be done with it.
08:05
For example get and post operations perhaps some objects can be updated with batch operations. I also want to see what exactly the request and response data looks like because again it helps avoid
08:23
the miscommunication and wrong assumptions. And if some of the endpoints take optional parameters then again you should point it out. Finally some of the endpoints might have specific permissions or might return different data in case the user does not have all permissions.
08:46
So for example perhaps managers or administrators see more data than the normal users and again this is very helpful to point out because I might assume as a user of your API that I always get this full response which would not be the case.
09:03
Now the only thing that is worse than missing documentation is obsolete documentation. So how do you keep your documentation fresh and up-to-date? The answer is that you should always strive to automatically generate that documentation and
09:23
there are different options of doing that. What I have gone for is usually starting with the code then generating schema from that code and then generating documentation based on that. And the schema in this case is sort of machine readable
09:41
description of your API listing again all the endpoints and different operations that can be done with them and then based on that you can generate user readable or human readable documentation, which is always up-to-date.
10:04
There are different ways to generate the schema. You might have heard about OpenAPI or Swagger and in general you should just check what your specific tooling supports. So for example if you're using
10:21
Django REST framework then that one has quite several packages that provide support for either OpenAPI or Swagger or some other way of ensuring that your schema and documentation is automatically generated. And it's really nice if you also
10:41
combine code with the descriptions so that again I can just copy-based and get started based on that. And finally the schema and auto-generation might not apply to just documentation, but also client libraries. So you can again take the schema and
11:01
generate something like Python library based on that which will help other developers and this does not apply to just Python, but you can generate the client libraries for a variety of languages. So let's talk about
11:23
standardization and why that matters. Following standards is good because it gives your users a sense of familiarity. If you create something that's completely unique and handcrafted then that means that nobody really has any previous experience to build on and
11:43
thus they have to learn everything about it. But if instead you follow widespread standards that are already in use then there's a good possibility that your users will either already have experience with that standard or just something similar enough and they can then transfer that knowledge to using your API and
12:05
get started faster. And just as importantly standards usually have some thought put into them so that helps you avoid common pitfalls. For example, when you think about web frameworks, they usually deal with things like password storage to help you not create security issues by storing them in plain text. And
12:27
standards usually do something similar by just helping you prevent all sorts of problems. And when it comes to APIs, my own current standard of choice is JSON API.
12:43
JSON API is not just a standard that, not just an API that uses JSON for response but it's an actual specification for building APIs and it was created by authors of Fember and it offers a pretty comprehensive solution for building APIs. I should also stress that JSON API is just one of the several options and
13:05
in your case perhaps you like something else, perhaps something else is better suited for your project. But the important thing is here that you use some of the existing widespread standards, be it JSON API, GraphQL or something different. And
13:26
going a bit deeper into JSON API, one of the most important aspects of it is that it defines a generic but flexible structure for API responses. So let's look at how JSON API responses are structured and
13:42
I'm going to use sort of a project management tool as an example which has which lets users create projects and epics and stories and add comments for them, sort of like Basecamp if you're familiar with that. So here is a simple
14:01
request for the projects listing and the response document as you can see has three top-level members, the links, the data and included. And let's look at them one by one. The links is important because it basically enables discovery of related endpoints. In this case
14:24
you can see that you can just follow a single link and get the next page of response objects. And in the same way your API route should also offer links to all of the individual resource pages like the same projects page.
14:45
Next up we have data which contains so-called primary data. This is basically the resource or resources that you asked for and in this case we asked for a list of projects. So that's exactly what we get, a list of resource
15:00
objects that each of which is an individual project. And each of those resources has type and ID which uniquely identified and they can also include links. In this case the project includes a link to the detail page of that project or canonical URL of that project. And
15:25
you can use this link to perhaps get more detailed information about the project or update the project. Next up we have attributes which is quite self-explanatory. In this case we get the project's creation timestamp
15:42
using the standard ISO format as well as the project name and description. And finally there can be also related objects returned with each project under the relationships object. So let's take a look at those. You can see that the project here has created by
16:05
relationship which is a single user and then additionally epics relationship which is list of epics that this project contains. And for each of those related objects you only have the type and ID and these two again uniquely identify the object and they then allow you to look it up in the included resources.
16:29
The included resources is the third top-level parameter that you might remember. So those are quite similar to the primary data and
16:43
they are basically useful for optimizing the number of requests that your application makes. So if you want to show detailed information about the project which also includes the name of the user that created this project then in this case the user's data is already included in the same response
17:02
meaning that you don't need to do multiple API requests and this is especially important if you are dealing with say mobile clients operating on a constrained bandwidth and CPU and whatnot. So how did that make you feel?
17:22
If you haven't used JSON APIs before then perhaps it looked a bit weird or bloated even. If you wanted to receive the name of the user that created the project then you'd have to go through quite a few layers of indirection to get that. And yet if I now gave you a response for another object from that same API and
17:44
told you that it has an updated by field which is also a user and I wanted to access the email of that user then you would know exactly how to do that because the entire structure of the response would be the same and the logic would be the same.
18:02
Furthermore if I gave you a completely different API unrelated to this one and told you that that one also uses JSON API then you would already know how to access that one as well because again the logic behind it is the same. And that's basically the power of standardization.
18:20
It brings familiarity and makes concepts that you have already learned applicable in new situations as well. Let's take a look at a few other features of JSON API. The fields returned as well as the related objects returned can actually be configured.
18:41
Here you have three requests for the projects listing. The first one is the same one with the default data we already looked at. The second one also requests comments of the project to be included in the response. And the third one says that I want comments of each project and
19:02
for the individual projects themselves I want nothing but the name and the comments. So again this helps you sort of optimize the responses and make them smaller for mobile clients and just not receive the data that you're not actually interested in.
19:24
You already saw that the list responses can have next and previous links which are used for pagination and the cool thing about that is that you don't as a client you don't need to know how the pagination is implemented in the server side. In my case I use cursor based pagination which means that server just gives you a link you follow that link and
19:46
then you get the next page of results. You might also want to swap that out for let's say page number based pagination but the good the idea is that the client does not care and you can change the server side
20:02
implementation without breaking any existing clients. I like cursor based pagination because it helps avoid perhaps problems perhaps not really problems where the client can ask for let's say one millionth page but then again it makes sense to ask for a specific page in some applications so
20:24
depends on your particular project which one you'd want to use and there are a few other features like filtering and ordering which are somewhat standardized using filter and sort parameters. I won't go into too much detail here, and then there are errors.
20:47
Errors do happen and you shouldn't always try to avoid them but perhaps instead offer your users easy and helpful way of figuring out what exactly went wrong and how they can fix that.
21:03
So here we have an example of some errors returned by the JSON API and you can see that first there are title and detail for each error which are sort of human readable but then there is also source which is machine readable location of
21:22
the specific thing that went wrong. In this case we tried to create the project but we can see that the name attribute was the one that contained some issue and you can also include error codes machine readable error codes so that
21:40
you would be able to more easily parse that on the client side. And again the goal here is basically to reduce friction and make the errors easier to deal with for your users. There are also special cases though for example when you need to return tons of data and
22:06
in those cases it might be that you would be better off with a different and more specialized format. Although I should also note that the visible plotiness of JSON API might not actually be a problem because the JSON would get compressed anyway.
22:25
But even better approach might be to include a link to downloadable data in your API response and sort of use out-of-the-band approach. Let me show you an example of what I mean.
22:41
So here we have some datasets API and we asked for one specific data set and what we get in response is sort of metadata. It contains the name of the data set and then it also contains the downloadable or link to the downloadable data but the data itself is not contained in the response.
23:03
And this has additional benefit that you can store that data, that potentially huge data in something like S3 and then just point your users to that instead of having to store it on your application servers.
23:21
So let's quickly cover the standardization once again. Basically the important part is that you pick a standard and choose it and implement it and what particular standard you use is a lot less important. Now most APIs don't deal only with public data or even if they do you might want to have some way of
23:46
identifying clients for various purposes like request limits. So you need to think about the authentication. How do you identify who is making that request as well as authorization? Meaning what is this client allowed to access?
24:03
And the best practice here depends largely on your specific project needs but I will cover two major use cases or options which are token-based authentication and OAuth 2. So token-based authentication is the simple approach where clients send an HTTP header
24:24
containing a simple token with each request as you can see on the example. And this is useful for client server situations where a client can be for example a native mobile application and then once the user logs into that application the server sends it an
24:44
authentication token which is then included in all subsequent requests. And if you think about it then session cookies are also sort of authentication tokens and if your API happens to be used only through the browser then perhaps that's all you need.
25:04
And then there is OAuth 2 for more complicated situations. Now OAuth 2 is basically meant for creating platforms. Think Facebook for example where a third-party application might request access to your data and then the platform verifies this request and
25:21
asks for users permissions and if the user consents then the application receives a token which is then both application specific as well as user specific. OAuth 2 is quite complicated protocol. It covers different use cases and different flows like mobile applications, web applications,
25:45
also applications with very limited user interface like some living room devices. And on the one hand this is good because again you're dealing with something that's already established and where lots of corner cases have been thought about and dealt with.
26:01
But the downside is that it also requires quite a bit of effort and attention when you're implementing that standard. Luckily though there are many packages that take most of take care of most of this plumping low-level work. For example if you're using Django then there is Django OAuth toolkit and
26:24
if you are not using Django there is the OAuth lib which is what the Django OAuth toolkit itself is built upon. For our API project we basically had to add some functionality on top of the Django OAuth toolkit.
26:41
Some of this was due to a few missing features in the Django OAuth toolkit, but most was really due to our application specific features and feature requests. And for example we also re-implemented the application developer views to be a bit more user friendly.
27:07
Next up I'd like to talk about versioning and I guess the most important part here is that you should think about versioning from the very beginning because it's really difficult to add it later because everybody will assume that your API will never change
27:23
because you never told them that it will. And if you have versioning from the beginning then it will be easier to manage these expectations. But you should also make very clear from the beginning how long each version is maintained as well as provide documentation on those support schedules and
27:44
release notes in case you come out with a new version. So let's look at how you can specify version in your API request. There are different options here and again, I'll cover two of the most popular ones.
28:05
So the first option is to have clients specify version as part of the accept HTTP header and this approach is more idealistic because the version used is sort of meta information which is then kept out of the URL bots for example.
28:25
So in the example you can see client tasks for the projects listing again and says that it wants to get the response in JSON format and using version 1.0.
28:40
But in reality headers are unfortunately a bit harder to use and test. For example, you can't test different versions in a browser. So in the real world, I have found that path-based versioning or URL-based versioning might make more sense. This is where you basically embed the version number in the URL.
29:03
Again, in this example, the client specifically asks for projects listing in version 1.0. And this can also improve debugging for example because when you print out the URL of the request then it sort of magically contains the version number as well.
29:26
Next thing to think about is how do you identify the versions? Some people like to use the integer based versions like v1, v2, but there are also date-based versioning schemes and personally, I have grown to like the date-based schemes because they're sort of less emotional.
29:44
You don't need to think about whether the next version will be v2 or just v1.1. But whichever way you choose you should mean you should make upgrades as easy as possible, again removing this friction, and this means having good change logs and
30:04
guides on how you can migrate from the previous version of the API to the next one. So this was the client side of things, but how about the server side? So there are two broad categories here. There are small incremental version changes, and then there are big breaking changes.
30:25
For incremental changes a nice approach is to use version transformers. So if you know Django, this is kind of similar to Django middlewares. Your core code basically supports only the latest version of the API and
30:42
when a request comes in with an earlier version then your transforming code knows how to translate this previous version to the next version and for the responses it's the same logic in a reversed way. So the transformer takes the latest version of the response and transforms it into an older version and
31:06
if you have multiple versions that you need to support then you can sort of stack them so that each of the transformers will sort of translate it to the next version and then the reverse with the responses.
31:21
And notably Stripe is using this approach in their API and there is a blog post available on their blog if you are interested in further details. For massive and breaking changes this won't really work though and in that case perhaps you will need to just
31:40
create a completely new API implementation and duplicate some code in the process. Now let's try looking at the same thing from client's perspective. Look at how some popular APIs are used and
32:00
let's say that I have some audio and I want to run speech recognition on it. I will be using Google Cloud Platform and AWS as examples and I think they're both pretty good examples because they both provide a single library that provides access to all of their services for both Google and Amazon.
32:21
So getting started with their libraries, the first thing that I went for is documentation, of course. In both cases the documentation was quite easy to find but slightly overwhelming just due to the sheer number of services that both Google as well as Amazon provide.
32:45
Nonetheless they both provide pretty good code examples so again, you can just get started really really quickly and have something running without much effort. And the first thing you'd have to do is installing the Python package for the SDK
33:04
in Google's case the Google Cloud package and in Amazon's case the Boto3. Next you will need to run through some authentication flows where you basically get an authentication token somehow from their API
33:21
they both provide command-line programs to do that and once you have an authenticated, there are quite thorough documentation to get you started. Moving on towards actual code, here is a very brief example for Amazon.
33:40
Basically you import the SDK package then you ask for the transcribed client and then you can run some methods on that transcribed client. Such as start transcription job, posit your audio data and eventually you will get that transcribed text back.
34:01
And in Google's case it's very similar, you import the speech client from the SDK, you instantiate it and then you can again run methods like recognize which take the audio data and give you the transcribed text back.
34:23
Both of those SDKs provide a common interface for all the services that either Google or Amazon offer. So if you've done the transcribe example, you also sort of know how to access something like S3.
34:42
You can also see that both Amazon and Google are very similar to each other in the code that you need to write to access them and again, this means that they are using common and familiar patterns without trying to invent something completely new and unique.
35:00
They both provide thorough documentation to get you started quickly and provide code examples and what you might not see here is that in both cases the client libraries are also at least partially automatically generated from some common crown of truth or schema that they have. So let's finish this up.
35:27
Basically documentation matters. It gives the first impression for your users and you should thus invest into it. Standards are great because they bring familiarity for your users.
35:41
Even though it doesn't matter which specific standard you follow. I suggest using automation to generate your documentation as well as client libraries so that they always stay up to date and finally just reduce friction as much as possible. By friction, I mean all those little bumps and issues that your users might encounter and which might drive them away.
36:06
So basically think of the humans. You can find the same slides in this URL or at my blog. Thanks for having me.
36:26
Thank you, Rivo, for this very interesting talk. We still have time for questions. So if you have a question, raise your hand and I'll bring the microphone to you. Thank you, great talk. You mentioned about auto-generating client libraries for APIs.
36:42
I don't know much about that. Can you tell me about like how to do that? What are the libraries or practices? So basically if you have the schema, for example, let's say in open API format, then you can generate the documentation for that using something like Swagger. And there are different tools that take this same schema and then generate a Python package, for example,
37:05
which means that your users will not have to make HTTP requests themselves, but instead they can ask for list of projects in a more intuitive way. And the same approach works for other languages as well.
37:20
So if you're targeting a variety of developers across different programming languages, then it's a really useful thing to use. I'm not sure about the specific tools. I suggest that you take a look at what your API framework, for example, offers. So if you're using something like Django REST framework, then there are some different options available.
37:46
You can also find something on open API specifications, I guess. So those are sort of the keywords to look for. You, thank you for the talk. It was really good.
38:02
You mentioned OAuthlib and I came across another one that's doing the same like OAuthlib. I'm wondering if you have heard anything about it. It seems to be something new. No, unfortunately not. All right. Okay.
38:22
Could you repeat that? Just want to mention that OAuthlib is a GPL, so depending on the project might be a bit problematic to use. OAuthlib was apparently deprecated in favor of using OAuthlib. So it has a choice between
38:45
BSD and deprecated or a GPL and still maintained. Okay. Thank you. Thanks for the info. Any more questions? In the back.
39:01
Hey. When you include it, when you showed the example where you included other resources, you used the ID as an integer. Doesn't it make sense to use the canonical URL here and only use canonical URLs? And what do you think of the role of hypermedia in REST APIs? So they were integers in this example where actually they were strings,
39:22
but the string contained just integer. You can also easily use something like UID or you could use the full URL as well. So it really depends. But again for the client, for the client, it should not make any difference because the client just has some
39:42
ID as a string and then it can look that up in the included resources. I think it does make a difference because like I see most clients constructing links and I kind of don't like it because it's like a very strong coupling of clients to APIs and I try to avoid it. So, I mean if you just put in a valid URL and you ensure somehow that the client uses it, maybe you have more loose coupling in the system.
40:06
Yeah, well in case of the included resources that you have in the included dictionary, they have the URL anyway. So you can look it up from there.
40:20
Thank you. I have a question about versioning. Is there some way to tell your clients through the API that a new version has been announced or that this version is deprecated or that you can offer them to upgrade to a new version or something? Good question. I'm not sure, but I guess it requires some
40:40
input or effort from the developer anyway who is using your API. So some companies just let you sign up with the email and then send you an email notification. There's actually an HTTP header. It's called the sunset header. It's not like widely used but you can find some RFCs describing it and you can announce the sunset of a version or specific endpoints using
41:05
sunset. Oh and another question, do we have time I guess? Okay, so we're implementing right now in our company adjacent API specification for our new version of our API and I was wondering
41:22
for mainly everybody here and if anybody else is using it and maybe some stories, some experience about the implementing it and moving forward with it. Because we didn't find any major companies using it and we were sort of worried
41:40
maybe we're using something really you know, not widely accepted or anything. I think you actually can find some pretty major companies using it but feel free to approach me during the breaks if you want more info. We have time for one more question. Anyone else?
42:03
So hello, it seems that the JSON API is missing some very common features like bulk operations or non-rest actions. So what's your approach on these questions?
42:22
It might support something with bulk operations, but I'm not sure I might have seen something in the spec but I haven't used it myself, so can't really comment on it, unfortunately. So we can even fit in one more.
42:40
So for the pagination you mentioned a cursor-based pagination. Is that some state you need to store on the server or does it somehow decode to a certain point in your list? It's basically just some data that the server can encode or decode
43:01
into a string and then that sort of a back string is passed to the client and you can also do authentication on top of that so that the client can't just change the data without the server being aware of it. Okay, thanks. So that wraps it up. Let's thank Riva again for this insightful talk.