[MUSIC] Now that you've learned a little about REST is and what it can do, we'll go through creating a simple RESTful Service. But first, let's talk about a few practices you should follow to create a well designed RESTful API. One's that I will talk about in this lesson are only a few basic practices for a good API. One practice for a good REST API is, use only nouns for your URI. For example, if you want to create a server for a university system with students and teachers, you can have a few URIs. Here, a student is identified through a numeric SID, and a teacher is identified through a numeric TID. In this table, you can see that the URI will end with /students, /students/SID, /teachers, /teachers/TID. Do not use URIs based on verbs like /GETallteachers. This is not a very restful API because it's not resource based. A good URI will direct the clients specifically to the resource to access. You will communicate the action you want to occur on that resource with the HTTP method in the request. From the table, to get a list of students, you would call the HTTP method GET on the URI ending with slash students. This will keep your APIs restful and consistent. Another practice to use is, GET methods should not alter the state of your resources. GET methods should do just as it implies, get resources. It's commonly accepted that the methods used to manipulate resources are put, post and delete. Following this principle will make your restful APIs consistent with other developers and easy to follow for future client application. A third practice to follow is, use plural nouns for your URI. Simplicity is key to a good API. When you're creating a service to deal with resources, it's better to keep it simple when referring to resources. Use /students to retrieve all students. And /students/three to get a specific student, three. Mixing and changing to a singular noun may cause confusion. So sticking to a single way of referring to your resources will help developers user your REST service. A fourth practice is use sub-resources for relationships between resources. This means that when a resource is related to another resource you can show the connection in the URI. For example, here the first API can be used to get all the courses of student three. The second API can be used to get the information on course two, connected with student three. Using subresources for relations can make your API easy to use and follow because the relationships are transparent in the URI. A fifth practice to remember is, use HTTP headers to specify the input output format. Headers are used to specify a lot of different properties. Two headers that are often left ambiguous by some developers but are very important in making your APIs easier to use are content type and accept. Content type defines the format of the message. Except defines a list of acceptable formats that can come as a response. Here, we can see that the request is formatted as a JSON and is accepting formats of JSON or text JavaScript. The response content is in the format of a JSON object, which is an acceptable format by the requesting client. Another practice for a well designed API is to provide users with filtering and paging for collections. When there are large data sets to parse through, good APIs will often provide filters to help search through the data. This can often be done by allowing parameters to be passed in after the symbol question mark. For example, the following API can be used to filter through all courses and only return those that are in the department of computing science. In this example, the API allows courses to be filtered based on the department passed in as a query parameter after the question mark. Also, using offset and limits can help users handle large sets of data. Allowing for filtering and paging for your APIs can save the client application from having to deal with the overhead of parsing through large amounts of data. It can also make responses quicker by only sending the needed information in the response. Another practice is to version your API. When your web services are being used by millions of users, changes to your API can break existing applications or services that call your APIs. To prevent future headaches for you and developers using your API, add version numbers. For example, here we added v2 to specify the version number. The last practice we will talk about in this lesson is provide proper HTTP status codes. There are many different HTTP status codes that can be returned as a response to a request. The most common and wanted response is status 200. This means that everything is working and functioning on the server side. However, there are many different kinds of status codes that can be used. For example, a 201 status code means a new resource has been successfully created. Also, a 204 status code means a resource has successfully been deleted. There are many different status codes and using the correct one during your RESTful API responses can help developers understand and use your APIs better. For more information on all the HTTP status codes take a look at the supplementary resources. Now that we've gone through some basic practices of designing a good API, let's actually look into creating a RESTful service. We will look into the proper steps and decisions you may need to go through in creating your own RESTful web service. Let's try and create a basic REST service where you can store, retrieve, and delete information about students and their courses. We've gone through some of these in our examples of good API practices earlier. So we can use our earlier APIs to create a simple REST service. First thing to think about is the services that I should provide. Because this is a web service about students and courses, there should be ways to retrieve information about the students, the courses and information about which courses students are taking. These will be our GET API's. In this table, you can see the basic GET APIs that I will provide with my web service. Naturally, I will also need to provide services to create, update and delete these resources. So here is a complete table on all the APIs that I should develop. As you can see, I've planned APIs to retrieve, create, update and delete student's courses, and student courses. Next, I create a resource representation class for a student. I'll leave you to create a course class. This Java file will have constructors and accessor methods for the ID, full name, and department for a student object. After, I create the Java file that handles the HTTP request that we planned earlier. This can be done through many pre-built Java libraries that provide the client library to communicate with a RESTful service. Some Java examples include Restlet, Spring, Jersey and RESTEasy. In this example, we will be using Jersey. Like I mentioned, these libraries provide the prebuilt methods to create a RESTful service and have specific syntax to access these methods. Here is an example of how to create a post service to create a student. After importing the necessary Java libraries, I write that the path for this REST service is /studentcourseapi, meaning all these APIs will start with this path. Jersey allows the support for Java API for RESTful Web Services, or JAX-RS. It provides pre-defined annotations that help map a resource class as a web service that can be accessed through HTTP requests. In the most basic terms, Jersey provides developers with easy to use methods that help create web services, simplifying and extending JAX-RS. In this example, Jersey requires that I state the acceptable HTTP method for this API in an annotation. I state at post to specify this will be a post method. The @consumes annotation determines the acceptable format that this API will take. I state that this will take only JSON format. We can allow various different formats like XML and plaintext, but for this API let's accept JSON. Next, atpath will specify the URI of this API. I state /students so that this API can be accessed at /studentcourseAPI/students. I can also state the returning format of the response. In this case, I state it will produce an XML message in the @produces field. After those specific Jersey annotations, we simply write the method that occurs once this API has been called. In this example, this API should create a new student. So I create a new student object and get the post parameters from the request to determine the name and department. For this example, I am using MyJaxBean to access the input that will be sent from a request. I save the new student object and return an XML message that says the properties of the new student I just created. I will leave the other APIs like the GET and PUT student in courses for you to create. Once all the API methods have been written and a Java object and files have be finished all you need to do is deploy it by using Apache or any other web server software. And that's your first Java REST service. Once everything has been deployed on your own machine, you should be able to access your API by using the following URL. Now, you can test your REST service by either creating your own client application that calls these URIs with a specific content for the API's you've created or by simply sending an HTTP request through the command line. Both will work in the same way. They will create an HTTP request with a JSON object that includes the information of the student we want to create. One tool you can use is CURL, which is a tool to transfer data from or to a server. The following CURL command will send a request to your server and invoke the post API that we created in this lesson. This CURL command, or your client application, will create an HTTP request that will be sent to your server in the URI specified with the JSON object containing a single student named James Dean in the department of Computing Science. This HTTP request may look something like this and is sent to the server through the web. Once the server receives this message it should call the method that we created earlier and create a new student with the properties that we sent in the JSON object. It will then send a response back to the client that may look like this. If you got a response using your creative application or CURL command, congratulations. You have now successfully created your own REST service. Try creating more difficult web services and don't forget some of the best practices for creating a well designed API. 1, use only nouns for your URI. 2, GET methods should not alter the state of your resources. 3, use plural nouns for your URI. 4, use sub-resources for relationships between resources. 5, use HTTP headers to specify input output format. 6, provide users with filtering and paging for collections. 7, version your API. 8, provide proper HTTP status codes. Following these practices will help you design great REST services. Good luck.
