RESTful and HTTP APIs in Pyramid Transcripts
Chapter: What is REST?
Lecture: Example service: GitHub
0:01 One thing you should do as you start to build services like this is look at well established, highly used services
0:09 and how they are working and how they're doing it. And you find a lot of examples of bad services and people not doing this well,
0:15 we're going to look at a couple of services starting with github, that I think are doing a pretty fine job with their services.
0:22 So over at developer.github.com we can go around and check out the getting started stuff, so there's all kinds of things we can work with,
0:31 there's oauth an authorization and what not, but let's look at the issues section here. So there's different things we can do, we can list the issues,
0:38 we can get a single issue, we can edit or create an issue things like that; we can even give a little thumbs up or something like that if we want.
0:46 Okay, so to get the issues across all repositories that we have access to, remember we're an authenticated user, we can just do get /issues.
0:55 Now, if we want to get them for a particular user we could do a /user/issues or for organization we could say /orgs/talkPython/issues
1:09 and that would show me all the issues that are assigned to this user across that organization all right.
1:14 So that's cool, and they give us a nice response, like ok the status code from this is going to be 200,
1:19 remember, there is get that probably makes sense and here's what this is going to look like, all right,
1:23 so let's pick another one, let's go down here to create an issue, now issues are associated with a particular repository,
1:29 so we're going to do a post to a repo who owns a repo, the name of the repo and issues. So maybe this is /repos/mikeckennedy/pyramid-rest-course/issues
1:44 and we did a post that would actually create one, new issue for this course, right, whatever, look at the full url right there.
1:49 Now, it says these are the things you can send in and they give us an example, these are the inputs, right,
1:55 I want to create a bug, the body is this, the title is I found a bug and then the response is going to be not 200, 201 created,
2:03 and again, they give us all the options, let's look at one more. What if we want to edit one, so these guys are actually using patch all right,
2:11 patch I didn't talk about, it's not that commonly used, but in this case, they're using the patch verb,
2:17 and they are going to basically apply that operation with a particular body to the url for that issue exactly, ok,
2:24 so here's the inputs, here's the response, everything was ok. Now, it's interesting here to think about what the response code should be,
2:32 if you're submitting all the details for that issue, maybe it should be 204 accepted but no content. If they were not sending anything back,
2:45 but maybe there is some state of that issue that is going to be basically it's in the system but they somehow didn't pass it in, right,
2:51 they might not roundtrip everything, so they because they send stuff back, they are doing 200, okay
2:57 so that is the github API and how they have created their API. You can use this for inspiration, I'll show you another one
3:04 that is working slightly different but also very well done next.