api design methodology
play

API Design Methodology Mike Amundsen API Academy / CA @mamund - PowerPoint PPT Presentation

Dec 28, 2022 •323 likes •1.54k views

API Design Methodology Mike Amundsen API Academy / CA @mamund Introduction Learning Hypermedia Clients Focus on the client side code Covers human-driven & M2M Lots of code! Due in fall 2015 @LCHBook #LCHProject

  1. API Design Methodology Mike Amundsen API Academy / CA @mamund

  2. Introduction

  8. Learning Hypermedia Clients • Focus on the client side code • Covers human-driven & M2M • Lots of code! • Due in fall 2015 • @LCHBook #LCHProject

  9. Hallway Conversations Podcast Hosted by Phil Japikse, Steve Bohlen, Lee Brandt, James Bender Website: www.hallwayconversations.com iTunes: http://bit.ly/hallway_convo_itunes Feed Burner: http://bit.ly/hallway_convo_feed Also available through Windows Store

  10. APIs for the Web

  15. Actually, we have a methodology already...

  16. Design Guidelines ● Craft [good/pretty/usable/stable] URIs

  18. Design Guidelines ● Craft [good/pretty/usable/stable] URIs ● Map domain actions to HTTP methods (CRUD)

  20. Design Guidelines ● Craft [good/pretty/usable/stable] URIs ● Map domain actions to HTTP methods (CRUD) ● Use the proper HTTP Status Codes

  22. Design Guidelines ● Craft [good/pretty/usable/stable] URIs ● Map domain actions to HTTP methods (CRUD) ● Use the proper HTTP Status Codes ● Document serialized objects as HTTP bodies

  24. Design Guidelines ● Craft [good/pretty/usable/stable] URIs ● Map domain actions to HTTP methods (CRUD) ● Use the proper HTTP Status Codes ● Document serialized objects as HTTP bodies ● Use HTTP headers responsibly

  26. Design Guidelines ● Craft [good/pretty/usable/stable] URIs ● Map domain actions to HTTP methods (CRUD) ● Use the proper HTTP Status Codes ● Document serialized objects as HTTP bodies ● Use HTTP headers responsibly ● Describe edge cases (async, errors, authN/Z)

  32. But there's a problem here...

  33. Those are not design guidelines..

  34. They are implementation guidelines!

  36. Ok, so what is a design methodology , then?

  39. Here's a simple seven-step procedure...

  40. Yep, seven steps.

  41. Let's design a Maze game API

  43. 1. List the Semantic Descriptors

  44. 1. List the Semantic Descriptors (the what?)

  45. 1. List the Semantic Descriptors (the what?) You know, the stuff!

  46. Ubiquitous Language Ubiquitous Language is the term Eric Evans uses in Domain Driven Design for the practice of building up a common, rigorous language between developers and users. This language should be based on the Domain Model used in the software - hence the need for it to be rigorous, since software doesn't cope well with ambiguity. -- Martin Fowler, 2006

  47. Ubiquitous Language Ubiquitous Language is the term Eric Evans uses in Domain Driven Design for the practice of building up a common, rigorous language between developers and users. This language should be based on the Domain Model used in the software - hence the need for it to be rigorous, since software doesn't cope well with ambiguity. -- Martin Fowler, 2006

  48. 1. List the Semantic Descriptors ● A maze ● A maze cell ● A switch ● Switch position ("up" or "down") ● The title of a maze cell ● A doorway connecting to cells ● An exit from the maze ● A list of mazes

  50. 2. Draw a State Diagram

  51. State Charts State Charts are compact and expressive – small diagrams can express complex behavior – as well as compositional and modular. -- David Harel, 2002

  52. State Charts State Charts are compact and expressive – small diagrams can express complex behavior – as well as compositional and modular. -- David Harel, 2002

  54. 3. Reconcile Names

  55. 3. Reconcile Names ● IANA Link Relation Values ● schema.org ● microformats ● Dublin Core ● Activity Streams

  56. 3. Reconcile Names ● maze ● start ● current ● exit ● north, south, east, west ● switch ● flip

  57. 3. Reconcile Names ● maze ● start (IANA) ● current (IANA) ● exit ● north, south, east, west ● switch ● flip

  58. 3. Reconcile Names ● maze ● start (IANA) ● current (IANA) ● exit (microformats) ● north, south, east, west (microformats) ● switch ● flip

  59. 3. Reconcile Names ● maze ● start (IANA) ● current (IANA) ● exit (microformats) ● north, south, east, west (microformats) ● switch ● flip edit (IANA)

  60. 3. Reconcile Names ● http://mamund.com/rels/maze (RFC5988) ● start (IANA) ● current (IANA) ● exit (microformats) ● north, south, east, west (microformats) ● http://mamund.com.rels/switch (RFC5988) ● flip edit (IANA)

  61. 3. Reconcile Names ● IANA o edit o start o current ● microformats o exit o north, south, east, west ● RFC5988 o http://mamund.com/rels/switch o http://mamund.com/rels/maze

  63. OK, that was the design part...

  64. But I still need to implement it, right?

  65. 4. Choose a Media Type

  66. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  67. Message-Passing The big idea is "messaging" - that is what the kernal of Smalltalk/Squeak is all about The key in making great and grow-able systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be. -- Alan Kay, 1998

  68. Message-Passing The big idea is "messaging" - that is what the kernal of Smalltalk/Squeak is all about The key in making great and grow-able systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be. -- Alan Kay, 1998

  69. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  70. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  71. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  72. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  73. 4. Choose a Media Type ● Use application/json, application/xml ● Collection type: Atom, OData, Collection+JSON ● Free-form: HTML, Siren, HAL, JSON-LD ● Invent your own semantic type

  76. Collection+JSON

  77. UBER+xml

  78. MAZE+xml

  79. 5. Write a Profile

  80. Profiles RFC A profile allows clients to learn about additional semantics that are associated with the resource. -- Erik Wilde, 2013

  81. Profiles RFC A profile allows clients to learn about additional semantics that are associated with the resource. -- Erik Wilde, 2013

  84. 6. Implementation

  85. 6. Implementation ta-da!

  92. And now we have running code!

  93. Wait, what's step seven?

  94. 7. Publication

  95. 7. Publication ● Publish your "billboard" URL ● Publish your profile ● Register new rel values and/or media types ● Publish the documentation ● Consider "well-known" URIs

  96. Now, you're done!

  97. Seven Simple Steps 1. List the Semantic Descriptors 2. Draw a State Diagram 3. Reconcile Names 4. Write a Profile 5. Select a Media Type 6. Implementation 7. Publication

  98. Some Final Advice

  99. Resources are an implementation detail

Recommend

SoC SoC Design Design Lecture 2: Design Methodology and Lecture Lecture 2: Design Methodology

SoC SoC Design Design Lecture 2: Design Methodology and Lecture Lecture 2: Design Methodology

SoC SoC Design Design Lecture 2: Design Methodology and Lecture Lecture 2: Design Methodology and Lecture : Design Methodology and : Design Methodology and Strategies Strategies Shaahin Hessabi Shaahin Hessabi Department of Computer

568 views • 27 slides
Sketching designs using the Five Design-Sheet Methodology http://fds.design Jonathan C. Roberts,

Sketching designs using the Five Design-Sheet Methodology http://fds.design Jonathan C. Roberts,

Sketching designs using the Five Design-Sheet Methodology http://fds.design Jonathan C. Roberts, Christopher Headleand, Panagiotis Ritsos @jcrbrts @ChrisHeadleand @ritsos_p 1 1. A teaching scenario 2. The FdS methodology 3.

945 views • 24 slides
Hardware Design with VHDL Register Transfer Methodology II ECE 443 Register Transfer Methodology:

Hardware Design with VHDL Register Transfer Methodology II ECE 443 Register Transfer Methodology:

Hardware Design with VHDL Register Transfer Methodology II ECE 443 Register Transfer Methodology: Practice In this lecture, we will look at several examples of RT methodology applied to a vari- ety of applications Examples include control of a

587 views • 54 slides
Design Thinking and Eco-Reps What is Design Thinking? A collaborative methodology for innovation

Design Thinking and Eco-Reps What is Design Thinking? A collaborative methodology for innovation

Design Thinking and Eco-Reps What is Design Thinking? A collaborative methodology for innovation that combines creative and analytical approaches from engineering, design, the arts, the social sciences, and the business world. Everyone is a

373 views • 20 slides
Introduction to design science methodology Roel Wieringa Slides based on Wieringa, R.J. (2014)

Introduction to design science methodology Roel Wieringa Slides based on Wieringa, R.J. (2014)

Introduction to design science methodology Roel Wieringa Slides based on Wieringa, R.J. (2014) Design science methodology for information systems and software engineering. Springer Verlag 30th May 2019 RCIS Brussels 1 Outline Design

620 views • 39 slides
Hardware Design with VHDL Register Transfer Methodology I ECE 443 Register Transfer Methodology:

Hardware Design with VHDL Register Transfer Methodology I ECE 443 Register Transfer Methodology:

Hardware Design with VHDL Register Transfer Methodology I ECE 443 Register Transfer Methodology: Principle We typically use algorithms to accomplish complex tasks Although it is common to execute algorithms on a GPU, a hardware implementation is

1.38k views • 76 slides
What do we need to consider? Design Installation Cleaning methodology Water Quality

What do we need to consider? Design Installation Cleaning methodology Water Quality

What do we need to consider? Design Installation Cleaning methodology Water Quality at Practical Completion Design The system design should be reviewed to make sure that it allows good water quality to be achieved and

313 views • 18 slides
Platform-Based Co-Design and Co-Development: Experience, Methodology and Trends Grant Martin and

Platform-Based Co-Design and Co-Development: Experience, Methodology and Trends Grant Martin and

Platform-Based Co-Design and Co-Development: Experience, Methodology and Trends Grant Martin and Jean-Yves Brunel Cadence Berkeley and Paris Electronic Design Processes Workshop, Monterey, April 21-23, 2002 1 CADENCE DESIGN SYSTEMS, INC.

521 views • 16 slides
CDA 4253/CIS 6930 FPGA System Design RTL Design Methodology Hao Zheng Comp S ci & Eng Univ

CDA 4253/CIS 6930 FPGA System Design RTL Design Methodology Hao Zheng Comp S ci & Eng Univ

CDA 4253/CIS 6930 FPGA System Design RTL Design Methodology Hao Zheng Comp S ci & Eng Univ of South Florida 1 Structure of a Typical Digital Design Data Inputs Control Inputs Control Signals Datapath Controller (Execution (Control

1.09k views • 59 slides
Toward a Design/Programming Methodology Although you must write code, you shouldnt be

Toward a Design/Programming Methodology Although you must write code, you shouldnt be

Toward a Design/Programming Methodology Although you must write code, you shouldnt be thinking about code when you first start thinking about solving a problem Analysis, Design, Implementation, but spiral through them, dont use the

280 views • 8 slides
Compact-2D: A Physical Design Methodology to Build Commercial-Quality F2F-Bonded 3D ICs Bon

Compact-2D: A Physical Design Methodology to Build Commercial-Quality F2F-Bonded 3D ICs Bon

Compact-2D: A Physical Design Methodology to Build Commercial-Quality F2F-Bonded 3D ICs Bon Woong Ku, Kyungwook Chang, and Sung Kyu Lim Georgia Tech Computer-Aided Design LAB Georgia Institute of Technology Contents 2/26 Introduction

597 views • 33 slides
Platform-based Design and the First Generation Dilemma By Jiang Xu and Wayne Wolf Dept. of ELE

Platform-based Design and the First Generation Dilemma By Jiang Xu and Wayne Wolf Dept. of ELE

Platform-based Design and the First Generation Dilemma By Jiang Xu and Wayne Wolf Dept. of ELE Princeton University April. 2002 Outline Background Typical system-level design methodology Platform-based design methodology First

288 views • 7 slides
Digital Design Methodology CENG/ELEC/SENG 399 Dr. F . Gebali, PhD, PEng ECE Dept. Faculty of

Digital Design Methodology CENG/ELEC/SENG 399 Dr. F . Gebali, PhD, PEng ECE Dept. Faculty of

Engineering Design Flow CAD Tools Summary Digital Design Methodology CENG/ELEC/SENG 399 Dr. F . Gebali, PhD, PEng ECE Dept. Faculty of Engineering http://www.ece.uvic.ca/ fayez 2012 c September 23, 2013 1 / 27 Engineering Design

673 views • 27 slides
Lana Abadie, March 2004 Content Objectives DB Design Methodology Readout network

Lana Abadie, March 2004 Content Objectives DB Design Methodology Readout network

Lana Abadie, March 2004 Content Objectives DB Design Methodology Readout network dataflow Use cases Entity relationship models Table design Conf.DB & PVSS (JCOP) C routine example : use case 3 & 4

299 views • 13 slides
INVENTIV Physical Design Implementation for 3D IC Methodology and Tools Dave Noice

INVENTIV Physical Design Implementation for 3D IC Methodology and Tools Dave Noice

INVENTIV Physical Design Implementation for 3D IC Methodology and Tools Dave Noice Vassilios Gerousis IVE Outline 3D IC Physical components Modeling 3D IC Stack Configuration Physical Design With TSV Summary

373 views • 18 slides
Managing Risk in Block Based Designs: A Front End Acceptance Methodology Kumar Venkatramani and

Managing Risk in Block Based Designs: A Front End Acceptance Methodology Kumar Venkatramani and

Managing Risk in Block Based Designs: A Front End Acceptance Methodology Kumar Venkatramani and Stefanus Mantik 22-23 April 2002 1 CADENCE DESIGN SYSTEMS, INC. Front-End Acceptance A methodology for the analysis of a proposed chip design

494 views • 14 slides
A MODEL BASED METHODOLOGY FOR SCA WAVEFORM DESIGN ENHANCING PORTABILITY APPLICATION TO THE FM3TR

A MODEL BASED METHODOLOGY FOR SCA WAVEFORM DESIGN ENHANCING PORTABILITY APPLICATION TO THE FM3TR

MINISTRE DE LA DFENSE A MODEL BASED METHODOLOGY FOR SCA WAVEFORM DESIGN ENHANCING

227 views • 12 slides
4. Multiagent Systems Design Part 2: The PROMETHEUS ems (SMA-UPC) methodology. Javier

4. Multiagent Systems Design Part 2: The PROMETHEUS ems (SMA-UPC) methodology. Javier

4. Multiagent Systems Design Part 2: The PROMETHEUS ems (SMA-UPC) methodology. Javier Vzquez-Salceda q Multiagent Syste SMA-UPC https://kemlg.upc.edu Methodological Extensions to Object-Oriented Approaches A means for agent

658 views • 17 slides
Evolving ASIC Methodology to Adapt to Technology and EDA Tool Advances Tom Russell Manager ASIC

Evolving ASIC Methodology to Adapt to Technology and EDA Tool Advances Tom Russell Manager ASIC

Evolving ASIC Methodology to Adapt to Technology and EDA Tool Advances Tom Russell Manager ASIC Front-End Methodology IBM Microelectronics Agenda Technology Advances Emerging Challenges Design Tool Advances ASIC Design Methodology

452 views • 23 slides
Design Innovation in Complex Systems Design: Integrating Design Thinking and Systems Thinking

Design Innovation in Complex Systems Design: Integrating Design Thinking and Systems Thinking

ASME International Design Engineering Technical Conference, Design Theory and Methodology (DTM) Conference, Presentation and Extended Abstract, 52938, August 2020. Design Innovation in Complex Systems Design: Integrating Design Thinking and

646 views • 5 slides
CONSIDERATIONS ON METHODOLOGY, STUDY DESIGN AND STATISTICAL APPROACHES Gerard PONS, MD, PhD

CONSIDERATIONS ON METHODOLOGY, STUDY DESIGN AND STATISTICAL APPROACHES Gerard PONS, MD, PhD

WORKSHOP ON REGULATORY AND SCIENTIFIC ISSUES RELATED TO THE INVESTIGATION OF MEDICINAL PRODUCTS INTENDED FOR NEONATAL USE EMEA London October 11, 2006 CONSIDERATIONS ON METHODOLOGY, STUDY DESIGN AND STATISTICAL APPROACHES Gerard PONS,

892 views • 57 slides
A Structured Routing Architecture and its Design Methodology Suitable for High-throughput

A Structured Routing Architecture and its Design Methodology Suitable for High-throughput

A Structured Routing Architecture and its Design Methodology Suitable for High-throughput Electron Beam Direct Writing with Character Projection Rimon IKENO 1 , Takashi MARUYAMA 2 , Tetsuya IIZUKA 3 , Satoshi KOMATSU 1 , Makoto IKEDA 1 , and

624 views • 30 slides
lntroduction BACKGRUOND Design Methodology @ Mindmapping cQllcl PT "r.;,.;. ::t,:,:iii.

lntroduction BACKGRUOND Design Methodology @ Mindmapping cQllcl PT "r.;,.;. ::t,:,:iii.

lntroduction BACKGRUOND Design Methodology @ Mindmapping cQllcl PT "r.;,.;. ::t,:,:iii. t*iTr :;*at':tP srl ;i:r---,r*_.,,', rsrrr TO^A5. -rrr Jf .hl:l:sd4F!l[ BREAKDOWN KEYWORDS THF CONCFPT What Would The Elements Be? * E:'e =l

134 views • 9 slides
A Hierarchical Design Methodology for Multibody Systems with Frictional Contacts Vijay Kumar

A Hierarchical Design Methodology for Multibody Systems with Frictional Contacts Vijay Kumar

A Hierarchical Design Methodology for Multibody Systems with Frictional Contacts Vijay Kumar GRASP Lab Mechanical Engineering and Applied Mechanics Computer and Information Science University of Pennsylvania Joint work with Bharath

387 views • 37 slides

More recommend