 Okay, now in the fourth part, we'll go away from all the theory and how we design things and we'll look at two actual APIs that exist in the web that are somewhat restful. They're somehow similar to what we've done. And one example is PayPal. So PayPal offers an API, a web service, a number of them actually, but it offers you ways to program applications where you can use PayPal. So you could write your own application and build in PayPal payment so that it, for example, fits into a larger thing if you want to implement a new billing system, you could automatically connect it to PayPal so you can write your own solution. And we'll look at the payments API, so how to do payments and we'll do only very few postman requests actually because there are only some things that I can do without doing actual payments. So we'll just have a look at it, but first we'll look at the documentation. And I'll be using version one. So you see that they are actually using versioning. They have a version number. There's also version two. Version two is quite different from the way that we have designed restful APIs. That's why I show you the old one. But as you see, they do, for example, is versioning to say that you can still use version one, but at some point we'll get rid of it. So the interesting thing is, first of all, what kind of resources do we have? Here we have payments. So we can handle payments. And that's just located at v1 slash payments. So that's sort of here is where PayPal puts the payment API. And the resources look a bit different from ours. But it's similar. So this is identifying their API. So please use version one of the payment API. And then here's the resource. So as you see, they don't use plural. They just say payment. But basically we're accessing the payment resource. And what we do in this case is we do a post request. And as we have learned, that means we are creating something. Intuitively, by looking at this URL and looking at the method, you know that a post request to this URL will create a new payment. That's exactly what it does. So that's how you can use it. Now, this is not enough. But typically you have to know what exactly you need to send. What is the representation you have to send to create a payment? What's the information needed? And that's found down here in the information. So it says, creates a sale, an authorized payment, or an order. So the different kinds of these things. And you'll then actually see the different parameters you need. So what kind of headers do you need to provide? How does the request body looks like? So for example, one thing that is required is you have to send something called an intent, which means what exactly is the payment about? Is it a sale, something a direct payment? Is it sort of an authorization? So something that will be later handled? Or is it an order? We're ordering something. And I mean, I don't know the details of PayPal, so I cannot go into all these details here, but essentially you have different ways of doing a payment. And then the other thing that is required is the payer, the source of the funds. So are we paying from a PayPal account, from a PayPal wallet, or are we paying using a debit card, for example? So different ways of doing that. And then you have a lot of optional things you can do, like saying, okay, what is the application context? And now I don't really know the details there, but you see there's a lot of stuff you can do. Or transaction, any kind of transaction that is related to the payment. So for example, what is the payment for? Who is the one fulfilling it? And so on. So you can add some details there. Like saying, what's the total amount? What's the currency? What, which part of it is tax? Which part of it is shipping? What's the description? What is it actually? Is there maybe some kind of custom or invoice information and so on? So there's a lot, a lot of stuff you can add, but it's all optional. And then there are actually, this is hate to us. So PayPal actually requires you somewhere down there. It's listed as a required thing, I believe. You have, no, it's not, but whenever I try it, it tells me it's required. You have to set redirect URLs. So that basically means what else can you do? You can, where do you go? Where sort of the return address when the PayPal payment is successful, if you press cancel, where do you go instead? So that's sort of other details we need. But see, this is a very common way of describing an API, which is say, what's the method? What's the endpoint? What's the URL? And then what's the kind of information needed? That's how we do a payment. That's something that actually last year I got to work. This year I somehow haven't managed, so we won't create a payment this time. But another thing we can do, create is one thing. Of course, another thing we might want to do is list all the payments that exist. So as you have learned, that should be a get request to the resource. So if we do that, we should get all the payments that we have existing. And if we look into the query, there are kind of different things we can ask for. For example, give me all the queries starting from a certain date until another date. So we can somehow restrict. So that's similar to, for example, the pagination or filtering that I have discussed. And we also, as you see, there is sorting. We could say sorted by the time the payment was created. So these things are possible. The get request does not have any request body. So there's no body we have to send. And then there's some information on what is it you will get back. As successful requests will give you 200 okay. And a JSON response body that lists all the payment details. And it looks like this. There is an array of payments. Each of them has an ID, create time, update time, blah, blah, blah. So lots of information. If I would just do this call, it will fail. And that's simply because most APIs and PayPal, of course, is no exception. They want you to have some kind of authorization. So you're only allowed to use the service if you have signed up. And that's a bit, that's sort of the bit you see here. There is some kind of header going on. And the application tells, here's my authorization information. Here's my token. That's something I will not cover here, but essentially I could go into postman and I can do get payment. So what I'll do here is I just call the right URL with a get parameter. And if I have logged in before, which is actually a post request, that one looks different. We'll cover that in the security lecture. But I have to do that first. Then I can do a get request on all the payments. And what I get back is the list of all my payments which happens to be zero. So I just get an empty array back. I haven't made any payments in my API. So this thing is sort of self descriptive. I tried to play around with creating a payment but I didn't manage. So it always says that my token is not valid. So I basically don't have the rights to create a payment. So most likely I would have to somehow either pay for the service or somehow update my access. But again, it's a request I can make and I can just get a 400 bad. You're somehow doing a bad request because you don't have the rights to do this. Forget about it. And now if we look at the details, there are other things we might want to do, show payment details, for example. And that just means instead of getting all the payments or a list of payments, I get a specific one. And that's now exactly the same case that we had in our to do app when we said do a get request to a specific user. So here we do a get request to a specific payment. Same thing really. So this is how PayPal works for the payments. As you see, there are lots of other things you can do. You can do orders and they might then look very similar. You can do post request to slash orders, creates a new order. So they're just different things you can do. Transactions, subscriptions and so on. So there's a lot of stuff that can be done in PayPal. But you see that just this information, just the method and the URL already tells you what this thing does just because it follows a certain style. And that's really where a lot of the useful nest lies in rest that it's very easy to figure out how to use an API. Another example, the second one I'll do in this lecture is going into GitLab because GitLab also has a REST API. And that one is actually a bit nicer. It's much closer to what we have covered. But GitLab, you know, from my assignments, for instance, I have created a project that is called Vef20 Assignments. This one has an ID. And of course in GitLab, you have a lot of different things. You have all the files that I uploaded. You have branches, you have commits, you have issues, for example, you could post an issue that something is wrong. There are other things, right? You have merge requests and so on. So there are lots of potential resources here. And actually the API for GitLab is quite nice. And again, it's very intuitive by just looking at the description. So one of the things you might want to look at is what kind of resources do we actually have in GitLab? And first of all, there are three groups. And we only look at the first one, but you can have projects, you can have groups, you can have standalone and so on. It's not so important, we just look at the projects one. There are different versions. So again, they do API versioning. They say we have upgraded to version four, but you can still use version three. And then they use some kind of keys. So you might have to have an authorization. Now, here are all the project resources. So if you have a project, here is a project. My project has a certain ID. Then I can do things with that. So first of all, I can access all the different commits through this request here. So I can just say, give me all the projects, give me the project with a certain ID, and then do repository slash commits. So this basically gives you all the commits for a certain project. Issues, please give me all the issues for a certain project. So again, this is exactly the same structure we have been using before. Projects slash ID identifies an individual project and then issues accesses all the issues for that specific project. And this continues. So members, projects slash ID slash members gives you all the members. Projects slash ID slash merge requests gives you all the merge requests. If we look at one specific thing, if we go into issues, for instance, you see what you can do. And you'll see all the different things you can do. Now list issues, how would that work? Well, it's just a get request to slash issues. So exactly the same as we have discussed. The get request says read all the issues and return them. Here they have done a shortcut. They have removed the slash project slash ID, but it essentially means the same thing. So as it says here, it's relative to the project. They have just removed that part from the URL. You can do certain things. For example, you can do filtering. Say only give me the issues that are opened or only give me the issues that are closed. You can search something I haven't discussed, but it's also often implemented to say only give me issues that have foo in the title and so on. So those are things you can do. It tells you what exactly you will get back. And here, for example, we can list all the issues for a specific project. And if you want a single issue, how would that look like? Well, according to what we learned, we would just add a slash and the ID of an issue. And indeed, if we go to single issue here, it says get slash project slash ID slash issues slash issue ID. So exactly as we would expect. Creating a new issue should be a post request. Same here. Editing an issue is probably a put request. So it's a put request to a specific issue. So without looking at all the details, if I really want to do this, of course I need to understand what is the information I need to send, how does my request look like? But by just seeing the method at the URL, I can get a very good idea of how this API works. Delete an issue is just a delete request. So there's a lot of stuff. And then of course it gets a bit more difficult. So subscribe to an issue. They have actually introduced a subscribe resource. So if you want to subscribe to an issue, what this means is you're actually creating a subscription resource for a specific issue for a specific project. So now it's getting tricky. But those things are very similar, which creating a new resource that is related. So this is a good example of a RESTful API. It's quite nicely structured. And as you see, these things get fairly complicated as you have large projects, as you have large services, large applications. The cool thing now is if I would use this API, I can implement my own website that somehow accesses GitLab. I don't have to use the actual GitLab website. So I can write a new application that just uses part of it. For example, let's say I just want to use the issue system, I could implement my own dashboard, my own HTML application that just shows all the issues. That's something that can be very useful for a company that has, for example, their code running on GitLab, but they might also have an already existing application that shows all, let's say all their test cases, then maybe they want to build a plug-in that also at the same time in the same application displays all the issues they have in their repository. So it can be a way of using data from different places. Okay, so that's what we have done. We have actually looked at two real examples. We haven't done so much postman, but the beauty of what we have done so far is really that we haven't cared about how this whole thing is implemented. We have just looked at the textual descriptions of how to use the API. And that's all we need to know. We don't need to know how, for example, PayPal has implemented this. We don't need to know what kind of database they're using. All we need to know is what kind of requests, what kind of URLs are there, how do we send the requests, and what is it we get back. So that's a nice thing. What we'll now do in the next step in lecture 17 is we actually implement this ourselves. So we will take the to-do application that we have designed. We will use Express to implement this. So we actually write the application. Then we'll deploy it to the cloud. So it actually runs on the internet, not just on our computer. And then we'll just add a database for the fun of it, which is not required, but it's of course a useful thing to actually have persistent data. Okay, so that's it for lecture 15 and 16. See you in lecture 17.