Intro to Web Services for technical communicators

1. Introduction to Web Services
Ed Marshall
2015 STC Technical Summit
Copyright 2015

2. 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

3. 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

4. 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

5. More Web Service Examples
• http://flickrpy.googlecode.com/svn/trunk/tags
2set.py
• http://docs.python.org/2/tutorial/interpreter.
html
• https://dev.twitter.com/
• https://developer.linkedin.com/
• https://developers.facebook.com/
6/19/2015

6. 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

7. 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

8. 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

9. 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

10. 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

11. 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

12. 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

13. 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

14. 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

15. 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

16. 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

17. 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

18. 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

19. 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

20. 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

21. Closing
• Thank you.
• Questions?
Ed Marshall
Marshall Documentation Consulting
ed.marshall@verizon.net
www.MarshallDocumentationServices.com
LinkedIn: Ed Marshall
Twitter: EdMarshall
+1 978-339-3095
6/19/2015