intro to web services - 2015 stc summit talk
TRANSCRIPT
Introduction to Web Services
Ed Marshall
2015 STC Technical Summit
Copyright 2015
Web Services – A Growing Area
• Web Service - An application that provides a Web API to provide a platform / language independent application
• Related to service-oriented architectures (SOAs)
• Uses several protocols to send / receive XML messages
6/19/2015
Who Uses Web Services
• Financial – mortgage companies, institutional traders, banks, etc.
• Web retail – Amazon Web Services, Nokia, and Netflix
• Software – Google and Dyn • Social Media – Twitter, Flickr, Picasa, You Tube,
Facebook, and Linked In
6/19/2015
Sample Web Services APIs
• Amazon Web Services – http://aws.amazon.com/tools/?nc1=f_dr
• Google – http://code.google.com/p/google-gdata/ https://developers.google.com/google-apps/documents-list/?csw=1#what_can_this_api_do
• Android – http://developer.android.com/index.html
6/19/2015
More Web Service Examples
• http://flickrpy.googlecode.com/svn/trunk/tags2set.py
• http://docs.python.org/2/tutorial/interpreter.html
• https://dev.twitter.com/ • https://developer.linkedin.com/ • https://developers.facebook.com/
6/19/2015
Sample Web Services Documentation
• Developer.android.com • https://help.dynect.net/dns-api-knowledge-base/ • Google.Gdata.Documentation.chm - http://code.google.com/p/google-
gdata/source/browse/#svn%2Fdocs • https://dev.twitter.com/docs • http://www.twilio.com/docs/api • Microsoft Tablet PC SDK documentation:
http://msdn.microsoft.com/en-us/library/ms840465.aspx http://msdn.microsoft.com/en-us/library/ms839522.aspx
• https://kenai.com/projects/suncloudapis/pages/Home
6/19/2015
Types of Web Services
• REST – Representational State Transfer • SOAP – Simple Object Access Protocol • XML-RPC – XML Remote Procedure Call • JSON-RPC – JavaScript Object Notation
Remote Procedure Call
6/19/2015
REST (Representational state transfer)
• RESTful APIs do not require XML-based web service protocols (SOAP and WSDL) to support their interfaces.
• REST is not a protocol, but a set of architectural principles. REST services provide simpler interfaces, all resources are identified in the request, and you can manage the resources from the REST API.
• REST services offer an easy-to-parse URL structure, that identifies the categories of data available.
• REST services use standard HTTP methods.
6/19/2015
REST (Under the Hood) Web Service APIs that adhere to the REST constraints are called RESTful. RESTful APIs have the following characteristics: • Specify a base URI, such as http://example.com/resources/ • Use a standard internet data type. Most commonly, JSON. Other types
such as valid Internet media type (for example, XML, Atom, microformats, images, etc.)
• Use standard HTTP methods (GET, PUT, POST, or DELETE) • Provide the current state of the resource in the call (referred to as
stateless) • Supply any resources needed via hypertext links
6/19/2015
Format for REST Commands
HTTP provides the following request methods (used by REST APIs): • GET – Lists / retrieves data from a record. Doesn’t change
the record • POST – Posts / stores writes data into a record. Creates a
new entry in a collection / data in a record • PUT – Replaces the entire collection with another
collection. • DELETE – Removes data from a record. Performs the same
operation every time.
6/19/2015
Web Application Description Language (WADL)
• A machine-readable XML description of REST web services. • WADL is the REST equivalent of SOAP’s Web Services Description
Language (WSDL).
Note, most developers still prefer good API documentation over reading WADLs or WSDLs.
6/19/2015
SOAP (Simple Object Access Protocol)
• Defines the communication method and the structure of the messages. Uses XML for the data.
• A SOAP service publishes a definition of its interface in a machine-readable document, using WSDL (Web Services Definition Language).
6/19/2015
XML-RPC
• An older protocol than SOAP. • Uses a specific XML format for data transfer
instead the proprietary XML format used by SOAP.
• An XML-RPC call is usually simpler and uses less bandwidth than a SOAP call.
6/19/2015
JSON-RPC
• Similar to XML-RPC but uses JSON instead of XML for data transfer.
• Defines a small number of data types and commands.
• JSON-RPC supports notifications (data sent to the server that does not require a response) and multiple calls can be sent to the server which can be answered out of order.
6/19/2015
Format for a JSON Request
A request is a call to a specific method provided by a remote system. It must contain three specific properties: • method - A String with the name of the method to be
invoked. • params - An Array of objects to be passed as parameters to
the defined method. • id - A value of any type, which is used to match the
response with the request that it is replying to.
6/19/2015
Format for a JSON Receiver
The receiver of the request must reply with a valid response to all received requests. A response must contain the following properties: • result - The data returned by the invoked method. If an
error occurred while invoking the method, this value must be null.
• error - A specified Error code if there was an error invoking the method, otherwise null.
• id - The id of the request it is responding to.
6/19/2015
Sample JSON-RPC Request
A simple request and response: Request: {“method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
Response <-- {"result": "Hello JSON-RPC", "error": null, "id": 1}
6/19/2015
Web Services / SOA resources
• Web Services A Manager’s Guide – Anne Thomas Mannes
• Service Oriented Architecture for Dummies – Judith Hurwitz, Robin Bloor, and Carol Baroudi
• Developing User Assistance for Mobile Apps – Joe Welinske
6/19/2015
Documentation Tools
• Adivo (www.adivo.com) • Sphinx documents python code
(http://sphinx-doc.org/) • Swagger – Used to create interactive examples
in your Web Services documentation (swagger.io) Live demo: http://petstore.swagger.io/
6/19/2015
Summary • Fast growing field – In 2014, cloud computing industry was
expected to grow to a $150 billion industry. • Combines traditional tech. writing w/ API skills > higher pay,
more flexibility, not as boring work • Work w/ “cool” (fun) technologies (Amazon, music, photos,
messaging, etc.) • Gets you into revenue generating areas such as marketing,
not just “cost centers”.
6/19/2015
Closing
• Thank you. • Questions?
Ed Marshall Marshall Documentation Consulting
[email protected] www.MarshallDocumentationServices.com
LinkedIn: Ed Marshall Twitter: EdMarshall
+1 978-339-3095
6/19/2015