Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Getting to Grips with RESTful APIs

54 views

Published on

Slides from the workshop delivered at the Evolution of Technical Communication 2018 conference. The workshop features an introduction to REST APIs followed by hands-on activities in which the participants (technical communication professionals) put themselves in developers' shoes used and some APIs and API tools like developers.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Getting to Grips with RESTful APIs

  1. 1. Getting to Grips with RESTful APIs Beginner API Workshop Petko Mikhailov Content Strategist PROS
  2. 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. 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. 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. 5. RESTful API BASICS https://evolution-of-tc.com/ 5
  6. 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. 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. 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. 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. 10. RESTful API BASICS https://evolution-of-tc.com/ 10 Platform APIsAll APIs Web APIs RESTful APIs SOAP APIs RESTful APIs
  11. 11. RESTful API BASICS https://evolution-of-tc.com/ 11
  12. 12. RESTful API BASICS https://evolution-of-tc.com/ 12
  13. 13. RESTful API BASICS Automotive industry analogy https://evolution-of-tc.com/ 13
  14. 14. RESTful API BASICS Automotive industry analogy https://evolution-of-tc.com/ 14
  15. 15. RESTful API BASICS Automotive industry analogy https://evolution-of-tc.com/ 15
  16. 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. 17. RESTful API BASICS Computer industry disaggregation https://evolution-of-tc.com/ 17 Web APIs are now everywhere!
  18. 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. 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. 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. 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. 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. 23. RESTful API BASICS https://evolution-of-tc.com/ 23 Documentation becomes important
  24. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 35. API Documentation https://evolution-of-tc.com/ 35 • MailJet • MailChimp • SendGrid Check out these API docs: Examples
  36. 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. 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:

×