REST architecture
This unit covers the following topics:
•Representational State Transfer (REST)
•JavaScript Object Notation (JSON)
•Example: Using REST APIs with Watson
5.1 What you should be able to do
After completion of this unit, you should be able to:
•Describe the characteristics of REST APIs.
•Explain the advantages of the JSON data format.
•Example of REST APIs using Watson.
5.2 References
The following publications are useful for further research on the topic presented in this unit:
•REST APIs
– ECMA-262 ECMAScript language standard, third edition
– RESTful Web services: The basics at IBM developerWorks
•Watch the following videos to learn more about Watson:
– IBM Watson is the platform for cognitive business
– IBM CEO Ginni Rometty describes a new era in technology and business
– Scientists at IBM Research have collaborated with 20th Century Fox to create the first-ever cognitive movie trailer for the movie Morgan using Watson.
– Watson and the Jeopardy! Challenge
5.3 What is REST?
Figure 5-1 What is REST?
Notes:
REST stands for Representational State Transfer. It is an architecture style for building resources on the World Wide Web.
For a website, HTML documents, images, and script files are all examples of web resources.
To retrieve or update a resource, perform an action through HTTP methods. To identify which resource to retrieve or update, REST uses a Uniform Resource Identifier, or URI, to describe the network location of the resource.
REST provides these HTTP methods:
•GET
•POST
•DELETE
•PUT
•OPTIONS
•HEAD
•TRACE
•CONNECT
The GET method is used to retrieve information from the server. When you use your browser to navigate to any URI, you use the GET method to get the HTML of that website. The query string containing the parameters needed for the request are sent in the URL by placing “?” at the end of the URI, then writing the parameters.
Each parameter is represented as a name-value pair. The parameters are separated by an ampersand (&). For example, the URI for a GET request can be like http://example.com/personDetail?firstName=Ahmed&age=28 or can be like http://example.com/personDetail/Ahmed/28.
The POST method is used to post data to the server. In this case, the parameters are posted in the body of the request, not in the URI.
The DELETE method is used to delete a resource from the server.
5.4 Applying REST to server-side applications
Figure 5-2 Applying REST to server-side applications
Notes:
In a more general sense, web resources represent a source of information. For example, HTML documents define the structure of a web page. Cascading Style Sheet (CSS) documents define the presentation of a web page, and image files provide a visual representation of information. With REST services, you treat server applications as web resources.
A REST service is now an entry point to an application on the server. It provides information from the server application. To call a REST service, use HTTP method verbs, such as GET, PUT, and POST. To specify which REST service to call, use a URI to describe the location of the resource on the server.
5.5 Example: Application model architecture for REST services
Figure 5-3 Example: Application model architecture for REST services
Notes:
In this example, Enterprise Java components represent the server-side application while the client-side of the application is based on JavaScript. The server-side application exposes a list of services as REST APIs. The client-side application calls these REST APIs using one of the HTTP methods. The request and the response can be either JSON or XML over HTTP Protocol.
You do not have to code the server side in Java and the client in JavaScript. There are plenty of people who use Groovy, Rails, Python, and other languages. They all can still use REST.
5.6 What is a RESTful web service?
Figure 5-4 What is a RESTful web service?
Notes:
A web service is a service exposed over the web to perform a certain function such as getStockPrice for a company. A RESTful web service, or REST service, is a web service that follows the principles of REST.
A web server hosts web resources: applications and sources of information, such as the IBM stock resource that contains information about the current stock price.
Identifiers uniquely references web resources. The resource path /stock/IBM/ represents the IBM stock resource on the server. The client uses HTTP methods as a uniform interface to interact with resources. In the example, to retrieve the current IBM stock price, send a GET operation on /stock/IBM.
5.7 Example: Sending an HTTP request to a REST service
Figure 5-5 Example: Sending an HTTP request to a REST service
Notes:
In this example, a client application running in the web browser sends an HTTP GET request for the resource on the server. Notice that the procedure for calling a REST service is exactly the same as making a request for a web page by using an HTTP GET request. When you navigate to a URL on your browser, your browser automatically sends a GET request to retrieve the requested page.
The name of the server resource is /account/101. This resource path represents an account record with an ID value of 101.
5.8 Example: Receiving an HTTP response from a REST service
Figure 5-6 Example: Receiving an HTTP response from a REST service
Notes:
The REST service running on the web server receives the HTTP GET request. It fulfills the request by returning an HTTP response message with information about the account in the message body. In the response message, the REST service writes the protocol type/version, HTTP status code, Content-Length, Content-Type, Date, and Response Body.
In this example, the protocol type/version is HTTP/1.1, the HTTP status code of 200 indicates that the REST service operation completed successfully. A human readable description of the status code which is OK appears after the code.
Content-Length contains the length of the response of message which in this example is 81 characters.
Content-Type describes the data type of the response which in this example is JSON.
Response Body is a JSON object that contains four name-value pairs, containing the values of the keys name, id, type, and balance.
5.9 REST characteristics
Figure 5-7 REST characteristics
Notes:
REST has the following characteristics:
•REST is a simple way of building services for client/server interactions, which are built on web resources.
•REST is an architecture, not a product. You build services that follow the REST architectural style.
•REST services follow standard web protocols such as HTTP. There is a misconception that REST can work solely over the HTTP protocol, but this is not entirely true. Although the most common scenarios for using REST is over the HTTP protocol, REST can be used over other transfer protocols like SMTP.
•REST services tend to use lightweight data models, such as JSON. It is used also for XML.
•REST services are a popular way for applications to interact with server-side applications.
5.10 Introduction to JSON
Figure 5-8 Introduction to JSON
Notes:
JavaScript Object Notation (JSON) is a text format for structured data. Its syntax is derived from the object literals of JavaScript, according to the ECMA-262 ECMAScript language standard, third edition, which is scripting language standard.
JSON is a platform-neutral and language-neutral data format.
The main design goal of JSON is to provide a minimal, portable, textual data interchange format.
JSON is not a markup language. Unlike XML, it does not use descriptive tags to encapsulate its data. For example, XML is a markup language because it uses tags like <title></title> to declare the title of the page. Whereas JSON is not a markup language.
JSON is built on two structures. A collection of name-value pairs known as objects and a list of values known as arrays.
5.11 JSON data types
Figure 5-9 JSON data types
Notes:
JSON has these data types:
•A string is a sequence of zero or more Unicode characters.
•A number includes an integer part and a fraction. Numbers can be prefixed by a positive or negative sign. It can also have an exponent.
•There are two data types to hold a group of values:
– An object: An unordered collection of zero or more name-value pairs. Objects are denoted by curly brackets. That means that the order is not guaranteed in JSON objects. For example, if you send a request {"name":"John","preferredColor":"Blue"}, it is not always guaranteed that the receiver will receive them in the same order.
– An array: An ordered sequence of zero or more values. Use square brackets to denote arrays. Order is guaranteed in JSON arrays.
•A Boolean is a literal value of either true or false.
•The keyword null represents a null value.
JSON values must be an object, array, number, or string, or one of the three literal names: false, true, null. JSON does not support the JavaScript keyword undefined. Either use null or another set value to represent an undefined value.
5.12 JSON data type: Objects
Figure 5-10 JSON data type: Objects
Notes:
JSON Object is an unordered collection of key/value pairs with these characteristics:
•Curly brackets ({ }) hold object declarations
•Colons separate object keys and values
•Commas separate each key-value pair
•Keys are strings
•Values can be any JSON data type
•Objects can be nested
In the example, the JSON object has three fields: Name, id, and email. The name field is another JSON object with two fields: First, and last.
5.13 JSON data type: Arrays
Figure 5-11 JSON data type: Arrays
Notes:
JSON Array is an ordered sequence of values with these characteristics:
•Arrays must begin and end with square brackets ([ ])
•Commas separate array values
•Arrays can be nested to represent multidimensional arrays
The figure shows two examples. The first example is an array of seven string values. The second example is a multi-dimensional array. Notice that the array can hold a mix of JSON data types.
JSON must start with either an object or an array at the top level.
5.14 What is Watson?
Figure 5-12 What is Watson?
Notes:
IBM Watson is a technology platform that uses natural language processing and machine learning to reveal insights from large amounts of unstructured data.
Watson analyses unstructured data. 80% of all data today is unstructured. Unstructured means not structured in machine-readable format. Unstructured data includes news articles, research reports, social media posts, and enterprise system data.
5.15 Watson Services in Bluemix
Figure 5-13 Watson Services in Bluemix
Notes:
The Bluemix Catalog contains several Watson Services, and new services are introduced periodically.
Watson Services include these applications:
•AlchemyAPI®: This app analyzes unstructured text and image content. You can use it to extract semantic metadata from content, such as information on people, places, companies, topics, facts, relationships, authors, and languages.
•Language Translation: Translates text from one language to another.
•Personality Insights: Personality Insights extracts and analyses a spectrum of personality attributes to help discover actionable insights about people and entities, and in return guides end users to highly personalized interactions. It takes a text as an input, and outputs the analysis of the personality according to the input text. You can try a demo of this service at the following link:
•Speech to text: This app converts the human voice into written words. It currently supports English, Japanese, Arabic, Mandarin, Portuguese, Spanish, and French.
5.16 Watson API Explorer
Figure 5-14 Watson API Explorer
Notes:
Watson APIs are exposed as REST APIs. You can interact with each API using one of the HTTP methods such as GET and POST.
Watson API Explorer is a public portal that contains documentation for the different Watson REST APIs, and also allows the user to call these REST APIs from the portal directly.
Watson API Explorer is based on Swagger, which is used to document REST APIs. You can access Watson API Explorer through this link:
5.17 Example: Watson API Explorer - AlchemyLanguage (Authors)
Figure 5-15 Example: Watson API Explorer - AlchemyLanguage (Authors)
Notes:
In this example, the Get Author REST API is called from AlchemyLanguage Service to get the author of an article in Reuters.
The Resource Path, which is the path of the exposed REST resource on the server, is /url/URLGetAuthors. The HTTP Verb used is GET, which is used to retrieve the author information of a particular URL. The example uses the following parameters:
•apikey: An API Key is required to call most of the Alchemy API services. You get this API key once you add AlchemyAPI service from Bluemix Catalog. However, it's optional for Get Author.
•url: The URL of the article that you would like to get the author name for.
•outputMode: Desired response format (default XML). In this example, json.
•jsonp: This is a JSON extension that is allowed to cross domains more easily. JSONP response can be passed as an argument to a callback function.
After filling the parameters, click Try it out. Watson API Explorer will build the Request URI, as shown below:
https://watson-api-explorer.mybluemix.net/alchemy-api/calls/url/URLGetAuthors?url=http%3A%2F%2Fwww.reuters.com%2Farticle%2Fus-africa-japan-idUSKCN112077&outputMode=json
The service URL is https://watson-api-explorer.mybluemix.net/alchemy-api/calls, the resource path is /url/URLGetAuthors, and the parameters passed are url and outputMode. Because it is a GET method, you can try it from your browser directly as well.
The JSON response is a JSON object with a collection of name-value pairs with keys status, usage, url, and authors. Authors is another nested JSON object that contains the key names which contains a JSON array. This JSON array contains the names of the authors of the article.
5.18 Checkpoint questions
Figure 5-16 Checkpoint questions
Notes:
(none)
5.19 Checkpoint answers
Figure 5-17 Checkpoint answers
Notes:
1. False. A JSON array is an ordered collection of values.
2. d. JSON is a light-weight data interchange format that is easy for applications to parse and generate, and JSON objects can be nested.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.