REST architecture and Watson APIs
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.
•Describe an 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 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:
Representational State Transfer (REST) is an architecture style for building resources on the web. Examples of resources for website include HTML documents, images, and script files.
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 (URI) to describe the network location of the resource.
REST provides the following 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 that contains the parameters that are needed for the request are sent in the URL by placing a question mark (?) at the end of the URI, and then, writing the parameters.
Each parameter is represented as a name-value pair. The parameters are separated by an ampersand (&). The URI for a GET request can be formatted as shown in the following examples:
http://example.com/personDetail?firstName=Ahmed&age=28
or
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 by using one of the HTTP methods. The request and the response can be JSON or XML over HTTP Protocol.
You do not have to code the server side in Java and the client in JavaScript. Although many people 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, such as applications and sources of information; for example, 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 our example, a GET operation is sent on /stock/IBM to retrieve the current IBM stock price.
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 the same as making a request for a web page by using an HTTP GET request. When you navigate to a URL in 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 and 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. In this example, it is 81 characters.
Content-Type describes the data type of the response. In this example, it is JSON.
Response Body is a JSON object that contains four name-value pairs, which contains 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 idea is not entirely true. Although the most common scenarios for the use of REST is over the HTTP protocol, REST can be used over other transfer protocols, such as 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, such as <title></title>, to declare the title of the page; 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 features the following 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 include 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, which 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 receives 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 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, or null). JSON does not support the JavaScript keyword “undefined”. 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 the following 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 our 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 the following characteristics:
•Arrays must begin and end with square brackets ([ ])
•Commas separate array values
•Arrays can be nested to represent multidimensional arrays
Two examples are shown in Figure 5-11. 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 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 analyzes unstructured data. As of this writing, 80% of all data is unstructured; that is, not structured in machine-readable format. Unstructured data includes news articles, research reports, social media posts, and enterprise system data.
For more information, see the video IBM Watson How it Works, which is available on YouTube:
5.15 Watson Services in IBM Bluemix
Figure 5-13 Watson services in IBM Bluemix
Notes:
The IBM Bluemix catalog includes the following Watson services (new services are introduced periodically):
•Natural Language Understanding
This service analyzes unstructured text content. You can use it to extract semantic metadata from content, such as information about people, places, companies, topics, facts, relationships, authors, and languages.
•Language Translation
This service translates text from one language to another.
•Personality Insights
This service extracts and analyses a spectrum of personality attributes to help discover actionable insights about people and entities, and in return guides users to highly personalized interactions. It takes a text as an input and outputs the analysis of the personality according to the input text. For an interactive demonstration of this service, see the following website:
•Speech to text
This service converts speech into written words. As of this writing, English, Japanese, Arabic, Mandarin, Portuguese, Spanish, and French are supported.
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 by 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. It 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. For more information about Watson API Explorer, see the following website:
5.17 Example: Watson API Explorer - Natural Language Understanding (Authors)
Figure 5-15 Example: Watson API Explorer - Natural Language Understanding (Authors)
Notes:
The Watson Natural Language Understanding service is used to analyze various features of text content. For more information, see the video Watson Natural Language Understanding Service Overview, which is available on YouTube:
In this example, the Analyze REST API is called from the Natural Language Understanding service to extract the author of an article in Reuters.
The Resource Path, which is the path of the exposed REST resource on the server, is /v1/analyze. The HTTP verb that is used is GET.
The following parameters are used in the example:
•Version: Watson services is available in different releases. The latest release of Watson Natural Language Understanding as of the time of this writing is 2017-02-27.
•Url: The URL of the article from which to extract the author name.
•Features: Natural Language Understanding provides several features for analyzing the text. This example shows the use of the metadata feature, which gets author information, publication date, and the title of your text or HTML content.
After the parameters are entered, click Try it out!. Watson API Explorer builds the Request URI, as shown in the following example:
https://watson-api-explorer.mybluemix.net/natural-language-understanding/api/v1/analyze?version=2017-02-27&url=http%3A%2F%2Fwww.reuters.com%2Farticle%2Fus-africa-japan-idUSKCN112077&features=metadata&return_analyzed_text=false&clean=true&fallback_to_raw=true&concepts.limit=8&emotion.document=true&entities.limit=50&entities.emotion=false&entities.sentiment=false&keywords.limit=50&keywords.emotion=false&keywords.sentiment=false&relations.model=en-news&semantic_roles.limit=50&semantic_roles.entities=false&semantic_roles.keywords=false&sentiment.document=true
The service URL is https://watson-api-explorer.mybluemix.net/natural-language-understanding/api/
The resource path is /v1/analyze, and all the parameters are passed in the query string of the URL because it is a GET method. Also, because it is a GET method, you can try it directly from your browser.
The JSON response is a JSON object with a collection of name-value pairs with keys retrieved_url, metadata, and language. Metadata is another nested JSON object that contains title, publication_date, and authors. Authors includes the key names, which contain a JSON array. This JSON array contains the names of the authors of the article.
5.18 Unit summary
Figure 5-16 Unit summary
5.19 Checkpoint questions
Figure 5-17 Checkpoint questions
5.20 Checkpoint answers
Figure 5-18 Checkpoint answers
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.