The document outlines a workshop focused on understanding RESTful APIs, including their definitions, importance, and how they facilitate communication between software components over HTTP. It covers the basics of API documentation, tools for interacting with APIs, and the essential components needed for good API documentation. The material emphasizes the growing prevalence of APIs across industries and the necessity for technical communicators to adapt and integrate with development processes.

1. Getting to Grips
with
RESTful APIs
Beginner API Workshop
Petko Mikhailov
Content Strategist
PROS

2. COVERAGE
https://evolution-of-tc.com/ 2
• RESTful API basics
• Observe some APIs and their documentation
• Try some APIs and API tools
• Look at the OpenAPI specification
• Hopefully Form an API TechCom community
etc2018@mailinator.com
What we’ll be talking about:

3. RESTful API BASICS
https://evolution-of-tc.com/ 3
• API definition:
A set of rules (interface) that two sides (programs, components,
services) agree to follow
What are APIs?

4. RESTful API BASICS
You can think of an API
as of a friendly waiter
ready to serve you.
https://evolution-of-tc.com/ 4

5. RESTful API BASICS
https://evolution-of-tc.com/ 5

6. RESTful API BASICS
https://evolution-of-tc.com/ 6
• API definition:
A set of rules (interface) that two sides (programs, components,
services) agree to follow
What are APIs?

7. RESTful API BASICS
https://evolution-of-tc.com/ 7
• API definition:
A set of rules (interface) that two sides (programs, components,
services) agree to follow
• Web API definition:
A set of rules (interface) that the two sides (programs, components,
services) which communicate with the HTTP(S) protocol agree to follow
What are APIs?

8. RESTful API BASICS
https://evolution-of-tc.com/ 8
• API definition:
A set of rules (interface) that two sides (programs, components,
services) agree to follow
• Web API definition:
A set of rules (interface) that the two sides (programs, components,
services) which communicate with the HTTP(S) protocol agree to follow
• RESTful API definition:
A set of rules (interface) that the two sides (programs, components,
services) which communicate with the HTTP(S) protocol using the
REST standard agree to follow
What are APIs?

9. RESTful API BASICS
So, what’s the big deal?
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 9

10. RESTful API BASICS
https://evolution-of-tc.com/ 10
Platform APIsAll APIs
Web APIs
RESTful APIs
SOAP APIs
RESTful APIs

11. RESTful API BASICS
https://evolution-of-tc.com/ 11

12. RESTful API BASICS
https://evolution-of-tc.com/ 12

13. RESTful API BASICS
Automotive industry analogy
https://evolution-of-tc.com/ 13

14. RESTful API BASICS
Automotive industry analogy
https://evolution-of-tc.com/ 14

15. RESTful API BASICS
Automotive industry analogy
https://evolution-of-tc.com/ 15

16. RESTful API BASICS
Computer industry disaggregation
https://evolution-of-tc.com/ 16
1960-1970
1970-1990
1990-2000
Mainframes
Software
PCs
Applications
OSs

17. RESTful API BASICS
Computer industry disaggregation
https://evolution-of-tc.com/ 17
Web APIs are now everywhere!

18. RESTful API BASICS
What does this mean?
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 18

19. RESTful API BASICS
https://evolution-of-tc.com/ 19
• New business:
 Now there are APIs for everything  domain experts, not
computer experts can write programs  software easier to create
then ever  startup easier to create by ever  more innovation
than ever!
 New type of company whose product is API
• Existing businesses:
 Companies can interconnect internal resources
 Can expose valuable data for external use
 IT unit of operations moves to API
For the industry:
What does this mean?

20. RESTful API BASICS
https://evolution-of-tc.com/ 20
• Computers, mobile, wearable, and IoT devices become interconnected
• Big data is put to use  Boost in AI
• Whole new ecosystems around APIs
• $2.2 trillion economy by the end of 2018
For the industry (continued):
What does this mean?

21. RESTful API BASICS
Cambrian explosion in technology!
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 21
And APIs are in the center of it!

22. RESTful API BASICS
https://evolution-of-tc.com/ 22
• TC profession keeps up with technology
• TC becomes more technical
• TC integrates with development
• TC is development
• Documentation becomes important
• TC can bring value
• TC can contribute to the whole development cycle
• Require “manual” documentation
• A stepping stone into programming
For Technical Communicators:
What does this mean?

23. RESTful API BASICS
https://evolution-of-tc.com/ 23
Documentation becomes important

24. RESTful API BASICS
Now is the right time to jump on the bandwagon!
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 24

25. RESTful API BASICS
Now is the right time to jump on the bandwagon!
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 25
But wait!

26. RESTful API BASICS
Are APIs difficult to learn?
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 26
The learning curve

27. RESTful API BASICS
https://evolution-of-tc.com/ 27
• Meant to be consumed not by humans but programs
• REST is a style, not a standard
• Typically explained by devs
• New and inconsistent terminology
What makes them difficult:
Are APIs difficult to learn?

28. RESTful API BASICS
https://evolution-of-tc.com/ 28
• Easier to learn than platform APIs
• Only 4 methods
• Don’t require knowledge of programming languages
What makes them easy:
Are APIs difficult to learn?

29. RESTful API BASICS
How do RESTful APIs work?
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 29

30. RESTful API BASICS
https://evolution-of-tc.com/ 30
• The methods
• The request
• The response
• The endpoints
• Header and body
• The parameters
• The data format (JSON, XML)
• Authentication
The main things:
RESTful APIs demystified

31. RESTful API BASICS
GET Asks the server to retrieve a resource.
POST Asks the server to create (and configure) a new
resource.
PUT Asks the server to edit/update an existing resource.
DELETE Asks the server to delete a resource.
https://evolution-of-tc.com/ 31
The four main REST methods

32. RESTful API BASICS
Request and response structures
https://evolution-of-
tc.com/
https://evolution-of-
tc.com/
https://evolution-of-tc.com/ 32

33. Activities
https://evolution-of-tc.com/ 33
Let’s try some things out!
Exploring APIs
• API request in the browser
• Numbers API
• Swagger Petstore API
• Post-Shift API
• Random Famous Quotes API
Exploring tools
• Postman
• cURL
• Open API specification
• YAML
• Stoplight

34. API Documentation
https://evolution-of-tc.com/ 34
What should be there in the API docs?
Minimum Viable
Documentation
(MVD)
• Schemas
• Overview
• Authentication
• Reference
• cURL examples
Full documentation
The MVD, plus:
• Getting Started
• Tutorials
• SDKs and sample apps
• Rate limiting and subscription plans
• Quick reference
• Best practices
• API glossary
• FAQ

35. API Documentation
https://evolution-of-tc.com/ 35
• MailJet
• MailChimp
• SendGrid
Check out these API docs:
Examples

36. TC API EXPERTISE
https://evolution-of-tc.com/ 36
• API methods
• How to pass parameters in the request
• How to interpret the response
• The JSON data format
• Postman
• cURL
• Open API spec
• YAML
• Swagger (and SwaggerHub)
• Stoplight
• What makes a good API documentation
• How to build API reference content out of the spec
• Git (and GitHub)
What does it take to become a TC API expert?

37. CREDITS
https://evolution-of-tc.com/ 37
• ProgrammableWeb
 I’d Rather Be Writing
 Swagger
 Kong
 Mashape
 Stoplight
 Mailinator
 MailChimp
 MailJet
 SendGrid
 Images’ copyrights belong to their respective holders.
This presentation has used material from: