Web Services and REST
3 types users Amazon offers web services
1. Associates: 3rd party site owners wishing to build more effective sponsored affiliate links to Amazon products, thus increasing referral fees 2. Vendors: sellers on Amazon platform looking to manage inventory and receive batch product data feeds 3. Developers: 3rd party developers building Amazon-driven functionality into their applications
REST best practices
1. Provide a URI for each resource that you want exposed 2. Prefer URIs that are logical over URIs that are physical. For example prefer http://www.boeing.com/airplanes/747 over http://www.boeing.com/airplanes/747.html Logical URIs allow resource implementation to change w/o impacting client applications 3. As corollary to (2) use nouns in logical URI and not verbs (resources are things not actions) 4. Make all HTTP GETs side-effect free 5. Use links in your responses to requests. Doing so connects your response with other data. It enables client applications to be self-propelled. That is, the response itself contains info about "what's the next step to take". 6. Minimize the use of query strings. Prefer http://www.parts.com/parts/00345 over http://www.parts.com/parts?part=id=00345 7. Use slash / to represent a parent-child/whole-part relationship 8. Use gradual unfolding methodology for exposing data to clients. A resource representation should provide links to obtain more details. 9. Always implement a service using HTTP GET when the purpose of the service is to allow a client to retrieve a resource representation, i.e. don't use HTTP POST
Adding marker to map
<body><scrpt> function initialize() { var myLatLng = {lat: 34.020, lng: -118.290}; var mapOptions = { zoom: 4, center: myLatLng } var map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions); var marker = new google.maps.Marker({ position: myLatLng, map: map, title: 'CS Dept' }); } var contentString = '<div id="content"><div id="siteNotice">CS Dept</div></div>'; var infowindow = new google.maps.InfoWindow({content: contentString}); google.maps.event.addDomListener(window, 'load', initialize); google.maps.event.addListener(marker, 'click', function() { infowindow.open(map, marker) } ); </scrpt> <scrpt async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initialize"></scrpt></body>
Three Categories of Web Services
> Big Web Services: involve XML messages that are communicated by the Simple Object Access Protocol (SOAP); API is formally described using Web Services Description Language (WSDL). These services are normally used for server to server communication, using additional protocols like XML Security and XML Encryption. > REST (Representational State Transfer) Services which use HTTP methods PUT, GET, POST, and DELETE > Cloud Services which provide cloud storage, application hosting, content delivery, and other hosting services. All three provide access through APIs
REST Server Responses
A server response in REST used to be an XML file; for example: <parts-list><part id="3322"><name>A</name><desc><D></desc><price currency="usd" quantity="1">12.22</price><uri>http://www.a.com/parts/3322</uri></part>........</parts-list> However, other formats can also be used; REST is not bound to XML in any way. JSON is response format recently used the most. Possible formats include CSV. One option not acceptable as REST response format, except in very specific cases is HTML, or any other format which is meant for human consumption and is not easily processed by clients. The specific exception is of course when the REST service is documented to return a human-readable document; and when viewing the entire WWW as a RESTful application, we find that HTML is in fact the most common REST response format.
Amazon Web Services Data Model
Amazon Standard Items (properties: ASIN, Media, Reading Level, MPN, Theatrical Release Date, Product Name, Release Date, Manufacturer, Sales Rank, Num Media, MPAA Rating, ESRB Rating, Age Group, Encoding, Product Type ID) Subtypes: External Identifier (properties: UPC, ASIC, EAN,...), Reviews (property: Review), Offering (properties: Merchant Name, Merchant SKU, Product Info, Merchant Price, List Price, Image URL (small), Image URL (medium), Image URL (large), Item Availability), Item Platform (property: Platform), Item Tracks (property: Track Name), Item Features (property: Feature), Item Accessories (property: Accessory), Contributor Type (properties: Artist, Author, Director, ...), Browse Node Map (property: Browse Node ID), Related Items
Apple iCloud for Developers
Apple's iCloud service places all information captured on any Apple device into the cloud, making it immediately available to all other Apple devices. 5GB (free) - 50 GB, 200 GB, 1 TB plans available. iCloud APIs available for iOS 5 - 12 and OS X 10.9+: CloudKit framework, Storage API for Documents, Storage API for key-value data storage, Storage API for Core Data, Fallback Store (iOS 7+), Account Changes (iOS 7+), Manage iCloud Content (iOS 7+), Xcode debugging (Xcode 5+), iPhone simulator support (iOS 7+)
Tesla Model S API
Base url: https://owner-api.teslamotors.com/ POST /oauth/token?grant_type=password Request: { "grant_type": "password", "client_id": "abc", "client_secret": "123", "email": "[email protected]", "password": "edisonsux" } Response: { "access_token": "abc123", "token_type": "bearer", "expires_in": 3888000, "refresh_token": "cba321", "created_at": 1538359034 GET /api/1/vehicles: retrieve a list of your owned vehicles (including vehicles not yet shipped) GET /api/1/vehicles/{id}: resources are read-only and determine the state of the vehicle's various sub-systems, id of the car
Microsoft Bing Maps REST Services
Bing Spatial Data Services are REST based services that offer 3 key functionalities: batch geocoding, point of interest (POI) data, and ability to store and expose your spatial data. Useed for performing tasks such as geocoding, reverse-geocoding, routing and static imagery. Find a location by address: http://dev.virtualearth.net/REST/v1/Locations/CA/adminDistrict/postalCode/locality/addressLine?includeNeighborhood=includeNeighborhood&maxResults=maxResults&key=BingMapsKey Find a location by query: http://dev.virtualearth.net/REST/v1/Locations/1%20Microsoft%20Way%20Redmond%20WA%2098052?o=xml&key=BingMapsKey Find a location by point: http://dev.virtualearth.net/REST/v1/Elevation/List?points=35.89431,-110.72522,35.89393,-110.72578,35.89374,-110.72606,35.89337,-110.72662&key=BingMapsKey Output formats: XML, JSON (output-JSON), JSONP (jsonp=callback), and PHP
More Complex REST Requests
Can include multiple parameters. Use HTTP GET parameters in the URL: http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe If you need to pass long parameters or binary ones use HTTP POST requests and include parameters in POST body GET requests for read-only queries (should not change state of server and its data). For creation, updating, and deleting data, use POST requests. (POST can also be used for read-only queries, as noted above, when complex parameters are required. While legacy REST services might use XML in responses (as one way of organizing structured data), REST requests rarely use XML. Newer REST services use JSON in their responses. One advantage of XML is type safety but in stateless system like REST you should always verify the validity of your input XML or otherwise
Cloud Services
Cover a variety of hosting services: Application hosting (AWS, Google App Engine, FireHost, Microsoft Azure), Backup and storage (AWS), content delivery (Netflix hosted by AWS), e-commerce (Amazon.com e-commerce), media hosting (e.g. Microsoft Azure, RackSpace, Streaming Media Hosting), DNS Protection Services (e.g. CloudFare), Consumer cloud storage (e.g. Apple iCloud Drive, Dropbox, Microsoft OneDrive, Google Drive). Access provided using two methods: 1. Dashboard, 2. Library based APIs embedded in Java, C#, Objective-C, and other binary library formats. All these services are commercial services that require monthly payments. Consumer cloud services provide limited, free basic storage.
Amazon Elastic Compute Cloud
EC2 Forms a central part of Amazon.com's cloud-computing platform, Amazon Web Services (AWS), by allowing users to rend virtual computers on which to run their own computer applications. EC2 encourages scalable deployment of applications by providing a web service through which a user can boot an Amazon Machine Image (AMI) to configure a virtual machine, which Amazon calls an "instance", containing any software desired. A user can create, launch, and terminate server-instances are needed, paying by the second for active servers -- hence the term "elastic". EC2 provides users with control over the geographical location of instances that allows for latency optimization and high levels of redundancy
Google Custom Search
Enables searching over a website or collection of websites. Places a Google search box on a website that allows users to search the site. Search results can be customized to match design of the site: Google form to be filled out to create the custom search box. Create a search engine: Google Custom Search enables you to create a search engine for your website, your blog, or a collection of websites. You can configure your engine to search both web pages and images. Search experience for users: site search for your website, topical search engine, use structured data with Custom Search <gcse:search></gcse:search> element is a placeholder where the search element (both search box and search results) will be rendered. If you want to render a search box in one area and display results in another do something link this: <div class="sidebar">Area 1 <gcse:searchbox></gcse:searchbox></div> <div class="main-content">Area 2 <gcse:searchresults></gcse:searchresults></div> https://cse.google.com/cse.js?cx=YOUR_ENGINE_ID
Google APIs
Google+, Android, App Engine, Chrome, Games, Google Maps, Google Apps, Google Play, Commerce, YouTube
Web Services
Idea of offering the capabilities/information on a web site via a programming interface, so application programs can more readily access the information on the site. APIs for accessing a website's information across the Internet.
Google App Engine
Lets you run Web Applications/Web Services on Google's infrastructure. No servers to maintain: you just upload your application (like AWS). You can serve your app from your own domain name or you can serve your app using a free name on the appspot.com domain (can limit access to members of your org) Supports apps written in: 1. Java environment (including JVM and Java Servlets), 2. PHP, 3. Python (App Engine also features two dedicated Python runtime environments, each of which includes a fast Python interpreter and the Python standard library), 4. Go (App Engine provides a Go runtime that runs natively complied Go code), 5. Node.js & Ruby (included in the "flexible environment") You only pay for what you use and there are no set-up costs and no recurring fees. Free daily limits quite high (657K API calls, 200h connect time, 5GB storage)
REST Services
Many websites now offering their facilities through REST Web Services. Can be used to access sites that perform the following functions: web search (Google Custom Search), Geolocation (Google Maps Geolocation API), Photo Sharing (Yahoo's Flickr), Social Networking (Facebook/Twitter), Mapping (Google Maps) Access provided in two ways: 1. Direct URL returning a response in 1+ formats (XML, JSON, PHP) 2. Library based APIs embedded in JavaScript, Java, C#, Objective-C, and other source and binary library formats. Many of these services now require or include OAuth user authentication. Oauth is a standard for clients to access server resources on behalf of a resource owner. Many services limit daily usage by a single website, and require payment when thresholds are breached.
REST as Lightweight Web Services
Much like Web Services as REST service is: platform-independent (don't care is server is UNIX, client is Mac, etc.), language-independent (C# can talk to Java, etc.), standards-based (runs on top of HTTP), and can easily be used in presence of firewalls. Like Web Services, REST offers no built-in security features, encryption, session management, QoS guarantees, etc. But also as with Web Services, these can be added by building on top of HTTP: for security, username/password tokens often used & for encryption, REST can be used on top of HTTPS (secure socket). One think not part of a good REST design is cookies: ST (state transfer) --> in good REST design operations are self-contained, and each request carries with it (transfers) all the info (state) that the server needs in order to complete it.
OAuth
Open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords. Mechanism used by companies such as Amazon, Google, Facebook, Microsoft, and Twitter to permit the users to share information about accounts with third party applications or websites. Designed specifically to work with Hypertext Transfer Protocopl (HTTP), OAuth essentially allows access tokens to be issued to 3rd party clients by an authorization server, with the approval of the resource owner. The 3rd party then users the access token to access the protected resources hosted by the resource server.
Flickr
Photo-sharing community with APIs provide viewing and uploading access. Request formats: REST, XML-RCP, SOAP. Response formats: REST, XML-RPC, SOAP, JSON, PHP. Supports JSONP. API Developer Kits available for 15 languages including ActionScript (Flash), Java (Android), .NET, Objective-C (iOS). Comprehensive numbe rof PAI methods for authentication, blogs, contacts, favorites, galleries, people, photos Ex query: https://api.flickr.com/services/rest/?method=flickr.photos.getRecent&api_key=f2cc26448280a762143ba4a865795ab4&format=json (remove format parameter for XML results) https required since Jun 2014 jsonFlickrApi({"photos":{"page":1, "pages":10, "perpage":100, "total":1000, "photo":[{"id":"6879682760", "owner":"8348059@n02", "secret":"1ac6c7e2c4", "server":"6220", "farm":7, "title":"DSC_0619", "ispublic":1, "isfriend":0, "isfamily":0}, ... ]
Amazon Web Services
Provide software developers direct access to Amazon's technology platform and product data. Developers can build businesses by creating Web sites and Web applications that use Amazon products, charging, and delivery mechanism. Using Web services, you can now enable your Web site visitors to add products to Amazon.com shopping carts, wedding registries, baby registries, and wish lists directly from your site/
REST vs Other Approaches
REST: Software architectural style for distributed hypermedia systems like WWW, quickly gained popularity through its simplicity SOAP: protocol for exchanging XML-based message, normally using HTTP, more robust way to make request, but more robust than most APIs need, more complicated to use XML-RPC: RPC protocol with XML as encoding and HTTP as transport, more complex than REST but simper than SOAP JSON-RPC: RPC protocol encoded in JSON instead of XML, very simple protocol (and very similar to XML-RPC)
REST
Representational State Transfer Style of software architecture for distributed hypermedia systems (i.e. the Web) (by Roy Fielding in 2000) that defines a set of constraints to be used for Web services. Ex. World Wide Web 3 fundamental aspects of the REST Design Pattern: 1. client, 2. servers, 3. resources (typically represented as documents, every distinguishable entity) Systems that follow Fielding's REST principles are often referred to as RESTful URLs: every resource is uniquely identified by a URL Simple Operations: PUT, GET, POST, DELETE
Amazon Associates Web Services Data Flow
Request comes in via XML or SOAP to Amazon.com XML/HTTP (REST) and SOAP processing layer Amazon.com XML/HTTP and SOAP Processing Layer communicates to Amazon.com Catalog Database Layer which sends data back to the REST layer. The REST layer either sends response to XSL Processor which can be returned to user via XSL processor or directy returns response to user via XML or SOAP
Postman
Tool for API testing, platforms include Chrome add-on, MacOS, Windows, and Linux native apps Free version comes with following support: unlimited Postman collections, variables, environments, and collection runs; Postman workspaces; Postman help center & community support; API documentation (1000 monthly document views), Mock Servers (1000 monthly mock server calls), Postman API (1000 monthly API calls), API monitoring (100 Monthly calls) Postman Pro and Postman Enterprise provide additional feature on a monthly subscription
Geocoding API
Use Geocoding API to find latitude/longitude of a local address, the process of converting addresses (like a street address) into geographic coordinates (like latitude and longitude) which you can use to place markers on a map or position the map. Result is lat/long Reverse geocoding is the process of converting geographic coordinates into a human-readable address. Geocoding ex request: https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY Reverse geocoding ex request: https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY Result ex: { "results" : [ { "address_components" : [{"long_name" : "277", "short_name" : "277", "types" : [ "street_number" ]}, {"long_name" : "Bedford Avenue", "short_name" : "Bedford Ave", "types" : [ "route" ]}, {"long_name" : "Williamsburg", "short_name" : "Williamsburg", "types" : [ "neighborhood", "political" ]}, {"long_name" : "Brooklyn", "short_name" : "Brooklyn", "types" : [ "sublocality", "political" ]}, {"long_name" : "Kings", "short_name" : "Kings", "types" : [ "administrative_area_level_2", "political" ]}, { "long_name" : "New York", "short_name" : "NY", "types" : [ "administrative_area_level_1", "political" ]},{"long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ]}, {"long_name" : "11211", "short_name" : "11211", "types" : [ "postal_code" ]}], "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA", "geometry" : {"location" : {"lat" : 40.714232, "lng" : -73.9612889}, "location_type" : "ROOFTOP", "viewport" : {"northeast" : {"lat" : 40.7155809802915, "lng" : -73.9599399197085}, "southwest" : {"lat" : 40.7128830197085, "lng" : -73.96263788029151}}}, "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA", "types" : [ "street_address" ]}, ... Additional results truncated in this example[] ... ], "status" : "OK" }
Order book
User: POST /order?id=1234 HTTP/1.1 Content-type: application/x-www-form-urlencoded ...order form data... -or- <?xml version="1.0"?> <order xmlns="...'> <bookId href="http://.../books/1234/"> <payment>...</payment> <shipping>...</shipping> </order -or- { "order": { "bookId": { "-href": "http://.../books/1234" }, "payment": " ... ", "shipping": " ... " } } Web Server: HTTP/1.1 200 OK ... <html> <a href="/orders/abcd">Order</a> </html> -or- HTTP/1.1 201 Created Location: http://.../abcd/ (rather than web pages being returned xml files are returned)
Get book list
User: GET /books/ HTTP/1.1 Web Server: HTTP/1.1 200 OK Content-Type: text/html ... <html> <a href="1234">Moby Dick</a> <a href="5678">XML QuickRef</a> </html> -or- Content-type: text/xml ... <?xml version="1.0"?> <books xmlns="..."> <book href="http://.../1234/"/><book href="http://.../5678/"/> </books> -or- Content-type: text/json { "books": { "book": [ { "href":"http://www./1234/" }, { "href": "http://.../5678/" } ] } }
Get book details
User: GET /books/1234 HTTP/1.1 Web Server: HTTP/1.1 200 OK Content-Type: text/html ... <html> <h1>Moby Dick</h1><a href="/order?id=1234">Buy!</a> </html> -or- Content-type: text/xml ... <?xml version="1.0"?> <book xmlns="..."> <title>Moby Dick</title>....<order href="http:///.../orders/"/> </book> -or- Content-type: text/json { "book": { "title": "Moby Dick", ..., "order": {"href": "http://.../orders"} } }
YQL Web Service
Yahoo Query Language is an expressive SQL-like language that lets you query, filter, and join data across Web services. With YQL, developers can access and shape data across the Internet through one simple language, eliminating the need to learn how to call different APIs. YQL exposes an SQL-like SELECT syntax. SHOW and DESC, SELECT commands. Open Data Tables enable developers to add tables for any data on the Web to our stable of API-specific tables. They are XML files that can be "plugged" into YQL open platform where the files descript how the YQL SQL-like language can be mapped into a web server or source on internet and once mapped, these data sources can be used by developers in many ways in YQL. You can use YQL to write and modify data on web services and applications using SQL keywords: INSERT, UPDATE, and DELETE. Tappid, query, number of results, radius, location (street, city, zip). Output formats: XML (default), JSON, JSONP (callback). YQL can be used for commercial purposes, with Yahoo approval. Per application limit (identified by API key): 100,000 requests per day. Per IP limits: /v1/public/*: 2000 calls per hour; /v1/yql/*: 20,000 requests per hour flickr, local.search, weather, amazon & fitbit (community tables) { "query":{"count": 10, "created": "2017-03-24T18:29:17Z","lang":"en-us", "diagnostics":{"publiclyCallable":"true","cache":[.....
Yahoo Services offered via REST
Yahoo! Search Web Services are all REST services. Flickr, Yahoo Query Language (YQL), Yahoo Partner Ads
Google Maps API
obtain API key <scrpt type="text/javascript"> src="https://maps.googleapis.com/maps/js?key=API_KEY"></scrpt> <scrpt type="text/javascript"> function initialize() { var mapOptions = { center: new google.maps.LatLng(-34.397, 150.644), zoom: 8 }; var map = new google.maps.Map(document.getElementById("map-canvas"), mapOptions); } google.maps.event.addDomListener(window, 'load', initialize); </scrpt></head> <body><div id="map-canvas"/></body></html> Zoom level controls distance above map. Higher values causes zoon to close in 4 map types: hybrid, roadmap, satellite, terrain one can alter map type with line: mapTypeId: 'satellite' or map.setMapTypeId('terrain');
