Tweet
Tweet

Slide 1

Slide 1 text

The Good and the Bad of the OpenStack APIs Miguel Grinberg | Everett Toews rack.to/good-bad-apis

Slide 2

Slide 2 text

2 About @miguelgrinberg ● Software Developer with Rackspace ○ Rackspace Private Cloud (os-ansible-deployment on Stackforge) ○ Member of the API Working Group ○ Heat & Horizon contributor ● Author & Speaker ○ O’Reilly’s Flask Web Development book, videos, webcasts ○ Flask & REST presentations at PyCon 2014, 2015 ● Blogger ○ Personal: http://blog.miguelgrinberg.com ○ Rackspace Dev Blog: https://developer.rackspace.com/blog/ www.rackspace.com

Slide 3

Slide 3 text

3 About @everett_toews ● Developer Advocate with Rackspace ○ Developer Experience ○ Founder of the API Working Group ○ Python OpenStack SDK contributor ● Author & Speaker ○ O’Reilly’s OpenStack Operations Guide ○ Presentations at OpenStack Summits, SXSW, OSCON, Gluecon, etc. ● Blogger ○ Personal: http://blog.phymata.com ○ Rackspace Dev Blog: https://developer.rackspace.com/blog/ www.rackspace.com

Slide 4

Slide 4 text

Overview www.rackspace.com 4

Slide 5

Slide 5 text

5 100 Ways to OpenStack www.rackspace.com

Slide 6

Slide 6 text

6 100 Ways to OpenStack www.rackspace.com

Slide 7

Slide 7 text

7 100 Ways to OpenStack www.rackspace.com

Slide 8

Slide 8 text

8 100 Ways to OpenStack www.rackspace.com REST APIs ● Everything goes through the APIs ● If it’s not in the APIs, it can’t be done!

Slide 9

Slide 9 text

9 100 Ways to OpenStack www.rackspace.com

Slide 10

Slide 10 text

10 100 Ways to OpenStack www.rackspace.com

Slide 11

Slide 11 text

11 100 Ways to OpenStack www.rackspace.com

Slide 12

Slide 12 text

12 100 Ways to OpenStack www.rackspace.com Python Client Libraries / SDK ● Runs in all Python platforms ● Python only

Slide 13

Slide 13 text

13 100 Ways to OpenStack www.rackspace.com

Slide 14

Slide 14 text

14 100 Ways to OpenStack www.rackspace.com Unofficial Client Libraries ● Not as complete as Python clients ● YMMV

Slide 15

Slide 15 text

15 100 Ways to OpenStack www.rackspace.com

Slide 16

Slide 16 text

16 100 Ways to OpenStack www.rackspace.com

Slide 17

Slide 17 text

17 100 Ways to OpenStack www.rackspace.com Command Line Clients ● Scripting friendly ● Output needs to be parsed or scraped

Slide 18

Slide 18 text

18 100 Ways to OpenStack www.rackspace.com

Slide 19

Slide 19 text

19 100 Ways to OpenStack www.rackspace.com Horizon Dashboard ● Good for quick interactive tasks ● No automation

Slide 20

Slide 20 text

20 What Is A REST API? ● REST: A software architecture style for creating highly scalable services. ● Client-Server interaction is based on HTTP requests sent to resource URLs. ● For a REST overview, watch my PyCon 2015 talk “Is Your REST API RESTful?” on YouTube. www.rackspace.com

Slide 21

Slide 21 text

21 The Good www.rackspace.com

Slide 22

Slide 22 text

22 Not Good… Great! Universal access All you need is an HTTP client! www.rackspace.com

Slide 23

Slide 23 text

23 Modular APIs ● Services are classified by type (identity, compute, image, network, etc.) ● They can be combined like LEGO bricks www.rackspace.com

Slide 24

Slide 24 text

24 The Catalog ● Lists all the services ● For each service its endpoints are defined ● Awesome concept... Hypermedia! www.rackspace.com

Slide 25

Slide 25 text

25 Authentication Flow ● Connect to the authentication URL ○ Send username, password and project ○ Receive token and catalog ● Connect to APIs from the catalog ○ Pass token in X-Auth-Token header www.rackspace.com

Slide 26

Slide 26 text

The Bad www.rackspace.com 26

Slide 27

Slide 27 text

27 Versioning Mess ● Which version should I use? ○ v2? v3? v2.1??? ● APIs should be designed to be extensible ● Versioning should be a last resort measure, reserved only for a major redesign www.rackspace.com

Slide 28

Slide 28 text

28 Bypassing the Catalog ● If a service is not in the catalog, then it should not be used ● Example from heat: www.rackspace.com

Slide 29

Slide 29 text

29 Client-Server Coupling ● Same team works on the server, API, client library and command line client ● APIs are mostly tested indirectly through the Python client libraries www.rackspace.com

Slide 30

Slide 30 text

30 Lack of Hypermedia ● Clients are forced to hardcode URLs ● Examples from glance and nova clients: www.rackspace.com

Slide 31

Slide 31 text

31 RPC Style Over REST ● APIs abuse the concept of “actions” ○ Glance: ■ /v2/images/{image_id}/actions/deactivate ■ /v2/images/{image_id}/actions/reactivate ○ Heat: ■ /v1/{tenant_id}/stacks/preview ■ /v1/{tenant_id}/validate www.rackspace.com

Slide 32

Slide 32 text

32 No Direct Browser Access ● No CORS support (Swift is the exception) ● Workarounds: ○ Set up third party WSGI middleware for CORS ○ Use an API proxy www.rackspace.com

Slide 33

Slide 33 text

33 Inconsistencies I ● Pagination ○ Works only for select resource collections ○ Nova, glance and cinder use limit and marker ○ Swift uses limit, marker and end_marker ○ Keystone uses page and per_page ○ Neutron does not paginate at all ○ No links for next and previous pages ○ No counts in most cases www.rackspace.com

Slide 34

Slide 34 text

34 Inconsistencies II ● Filtering ○ Most filters check for equality, very few support pattern searches ○ No way to check for ranges or multiple values ○ Lots of resource collections do not support it ● Sorting ○ Support across OpenStack is almost non-existant www.rackspace.com

Slide 35

Slide 35 text

35 Inconsistencies III ● Metadata ○ Nova and glance use a /metadata appended to the resource URL ○ Swift uses request and response headers, on the actual resource URL www.rackspace.com

Slide 36

Slide 36 text

36 Inconsistencies IV ● HTTP Response status codes ○ Asynchronous requests: 200 (bad) vs. 202 (good) ○ Incorrect request method: 404 (bad) vs. 405 (good) ○ Resource creation: 200 (bad) vs. 201 (good) www.rackspace.com

Slide 37

Slide 37 text

37 The Solution www.rackspace.com

Slide 38

Slide 38 text

The API Working Group “To improve the developer experience of API users by converging the OpenStack API to a consistent and pragmatic RESTful design. The working group creates guidelines that all OpenStack projects should follow for new development, and promotes convergence of new APIs and future versions of existing APIs.” 38 www.rackspace.com

Slide 39

Slide 39 text

39 Deliverables ● Analysis ● Guidelines ● Reviews ○ APIImpact ● Collaboration ● Bugs? www.rackspace.com

Slide 40

Slide 40 text

40 Traction www.rackspace.com ● “I like this, many thanks.” ○ John Garbutt, Nova PTL [1] ● “I also seek feedback from the API-wg” ○ Salvatore Orlando, Neutron Core [2] ● “dovetails with developer focused API errors” ○ Rochelle Grober, Logging WG [3] ● “Everett, Thanks! Just joined!” ○ Alex Xu, Nova [4] [5]

Slide 41

Slide 41 text

41 How To Help ● The API Working Group ● Meet with us ● Chat with us ● State of the API Working Group ○ 3:40pm - 4:20pm • Room 301 ○ rack.to/api-wg www.rackspace.com

Slide 42

Slide 42 text

Thank You! @miguelgrinberg @everett_toews rack.to/good-bad-apis Did we mention we’re hiring? bit.ly/RackerTalent