A very common server API protocol is RESTful JSON. The URL structure is predictable and it allows both sides to work toward a common goal: clear communication and data transfer. There are various aspects to consider and understand when writing a client API to a RESTful JSON server. Once those are set, development is smooth.
- [Instructor] So, lets get started by talking a little bit about what REST actually is. Well, REST stands for Representational State Transfer and is an architectural style for distributed hypermedia systems. That's how it was described when it was presented in 2000 by Roy Fielding and also, since it was 2000, quite a while back, it's okay to use the word hypermedia. Now, since it's a style, there's not really rules that go along with a RESTful API. It's principals or guidelines and the idea is it's a way to provide consistency in the API definition.
However, that also leaves room for some variation. So, whenever you're developing against a RESTful API, you need to make sure that you have access to whatever documentation and or the developers to understand exactly how things are going to work in that particular case. To learn more specifics about RESTful and RESTful APIs, I recommend the website, restfulapi.net. It's very helpful, explains a lot of things, and also has links to Roy Fielding's dissertation and the guiding principals of REST.
Also, it's very common when using a RESTful API that the data being passed back and forth is in the JSON protocol. So, it's very common to refer to this type of API as RESTful JSON. Now let's look at some differences between a typical API defined by the URLs and a RESTful API. It's pretty common for you to specify the file name at the end of the URL. In the example here on the left side, we have authors.php.
Typically, that would probably return back all of the authors from the database on the server. If you wanted a specific author, you would specify the ID in the query string like the second example. You got the question mark, ID, equal, in this case, five. That should return back the author whose ID is five. Similarly, you might have an endpoint for fetching books such as books.php in third example where we specify in the query string the author ID five.
This might return back all the books that were written by the author who has the ID five. In the fourth example, we're again going back to the authors.php file and specifying the book ID equal 123. In this case, we would expect to return back the author of the book that has ID 123. On the right side, we have the same examples, but in a RESTful API. To access all of the authors, we'd simply just put authors at the end of the URL.
If you're searching for a specific author, you might have authors, slash, and then the ID. There may be some other designations, such as ID, slash, ID number, but, in this case, it's just the ID. In the third example, we want to get back all the books for that same author, so we have authors, slash, five for the ID, slash, books. And, finally, if we want to get the authors for a given book, we might have something like book, slash, the ID of the book, slash, authors.
It's easy to read by humans. You can also write it simply by typing out the text and it can be made even easier if you use an online formatter. And, it's also easy for machines to parse and to generate. We'll be looking at that a lot in this course. For more specific information on JSON, you can go to json.org. It gives you a lot of the details and examples of how JSON works, particularly how the formatting works. The basics of that, JSON is made up of objects Objects are in curly braces and they contain members.
What's a member? Well, a member, if you look at the second bullet point, is a pair and possibly other members. Again, going down the line, we can see that a pair is a string, value pair. A string is the key and the value, of course, is the value. There can also be arrays. Arrays are specified by the square braces. And, inside arrays are elements. Go to the next bullet point, we see that elements are made up of values and other elements. And, finally, what is a value? A value can be a string, a number, an object, an array, which of course we already saw the definition of, true, false, and null.
And, those are more of the keywords that specify for bullion values and of course a null value. So, a pair can be a string, value pair and the value can be one of those. An array can contain elements and an element is a value. A value can also be an object. An object has members. So, you can see that the definitions can be a little bit cyclical, but they're all here and everything can be pretty clearly defined and readable. Let's look at an example to help clarify it a little bit.
In our example here, we have several values inside of one member. Now, this might look familiar to you if you've ever dealt with dictionaries. So, in our case, we have a few values. We have the ID is equal to five which is an INT because there's no quotes around it. We also have a title that is equal to a string of RESTful Online Course. And then, our third key value pair is keywords for the key and the value is an array of strings, restful, server, json, and ios.
Now, this is just one member because it's all within curly braces, but you can see how you can have multiple members or values inside an array. Again, you may have seen this before when printing out the value of a dictionary in iOS. So, it probably looks a little bit familiar already. This is the type of data we'll be dealing with throughout this course parsing from our objects into data and back and forth all interacting with the server. So, let's get started.
- Create, read, update, delete (CRUD)
- RESTful fetching one item
- REST response handling of JSON
- Creating new objects on the server
- Codable for arrays and dictionaries
- Enumerations and Codable