API Design Anti-patterns: How to identify and avoid them

Slide 1

Slide 1 text

© 2025 All Rights Reserved API Design Anti-patterns: How to identify and avoid them Hari Krishnan https://www.linkedin.com/in/harikrishnan83/ https://x.com/HariKrishnan83 https://github.com/harikrishnan83

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Representational State Transfer (REST) Everything is treated as a resource Interactions are stateless Use of standard HTTP methods Predictability and consistency through Uniform Interface Abstraction by allowing for a layered architecture HATEOAS (Hypermedia As The Engine Of Application State) And more … https://ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf Roy Fielding

Slide 4

Slide 4 text

Richardson Maturity Model (RMM) A model of restful maturity Level 0: The Swamp of POX (Plain Old XML) Level 1: Resources Level 2: HTTP Verbs Level 3: Hypermedia Controls (HATEOAS – Hypermedia As The Engine Of Application State) https://www.crummy.com/writing/speaking/2008-QCon/act3.html Leonard Richardson

Slide 5

Slide 5 text

© 2025 All Rights Reserved Level 0: The Swamp of POX (Plain Old XML) • RPC (Remote Procedure Call) style endpoints • Accept XML or JSON payloads • Ex: A single POST /api endpoint handling all requests • Disadvantages • No separation or identification of resources • No HTTP method semantics, thereby cannot leverage HTTP infrastructure for caching etc. • No HTTP status code semantics, thereby usually have to define custom error codes POST Response

Slide 6

Slide 6 text

© 2025 All Rights Reserved Level 1: Resources • Each resource gets its on URI • May still accept XML or JSON payloads just like Level 0 • Disadvantages • No HTTP method semantics, thereby cannot leverage HTTP infrastructure for caching etc. • No HTTP status code semantics, thereby usually have to define custom error codes POST Response

Slide 7

Slide 7 text

© 2025 All Rights Reserved Level 2: HTTP Verbs • Make use of HTTP methods (e.g., GET, POST, PUT, DELETE) in a way that aligns with REST principles • User of HTTP Status Codes • Adds significant value to API usability by providing a more predictable interaction model

Slide 8

Slide 8 text

© 2025 All Rights Reserved Level 3: HATEOAS • Incorporates Hypermedia as the Engine of Application State • Links to understand what actions to take next Advantages: • No hardcoding of URLs in client • Workflow changes managed by Server Challenges: • Implementation complexity for client and server • Learning curve Examples: • Paypal - https://developer.paypal.com/api/rest/responses/#link-hateoaslinks • Github - https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28

Slide 9

Slide 9 text

Postel’s Law / Robustness Principle “be conservative in what you do, be liberal in what you accept from others” Examples: • Tolerating extra fields in inputs • Ignoring unknown query params • Allowing default values for some fields https://www.ietf.org/rfc/rfc793.txt Jon Postel

Slide 10

Slide 10 text

© 2025 All Rights Reserved Robustness Principle • Positive implications • High levels of tolerance • Resilience against minor deviations • However, what about • Implementation complexity • How much do we tolerate

Slide 11

Slide 11 text

Hyrum’s Law “With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.” https://www.hyrumslaw.com/ Hyrum Wright

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Resilience “The ability to recover from failures and continue to function” • Recovering gracefully • Expecting the unexpected • Handle and / or communicate disruptions

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

© 2025 All Rights Reserved Idempotency “the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request” - https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods • Idempotent Methods: • GET • PUT • Safe methods https://www.rfc-editor.org/rfc/rfc9110.html#name-safe-methods • Non-idempotent Methods: • POST

Slide 17

Slide 17 text

© 2025 All Rights Reserved Why “Idempotency”? • Fault tolerance - safe retries • Consistency • Low complexity for Clients, Middleware • need not worry about request state • simpler error handling • Improves Caching • In line with HTTP Statelessness • Predictability

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

© 2025 All Rights Reserved • Not “Idempotent” • GET will be cached, so technically this will not even work • Any other issues? • What is the alternative? • GET /articles/123 # Retrieves the article without affecting view count • POST /articles/123/viewed # Increments the view count HTTP GET that updates / creates data

Slide 24

Slide 24 text

Slide 25

Slide 25 text

© 2025 All Rights Reserved POST to GET a resource • Catchability is lost • POST is not idempotent, so API clients may not perceive this as repeatable or safe • Alternatives • HTTP QUERY Method - https://www.ietf.org/archive/id/draft-ietf-httpbis- safe-method-w-body-02.html • Any others?

Slide 26

Slide 26 text

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Slide 29

Slide 29 text

Slide 30

Slide 30 text

Slide 31

Slide 31 text

Slide 32

Slide 32 text

Slide 33

Slide 33 text

© 2025 All Rights Reserved Smart Defaults • Consumers may start depending on your defaults • Screens may be designed to show max ten items • Users may expect that only popular items are at the top • If Front End does not explicitly state it wants most popular items first • And switches to sorting by price, users will see lowest price items first • Sounds familiar? Hyrum’s law

Slide 34

Slide 34 text

Slide 35

Slide 35 text

Slide 36

Slide 36 text

© 2025 All Rights Reserved Avoid “nullable: true” • Adds unnecessary complexity in handling the null • How does one interpret the null? • Is ”null” a true or false when it is applied to a Boolean • Which “enum” value applies when I send null • And more… • Use “optional” instead

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Slide 40

Slide 40 text

© 2025 All Rights Reserved API Design – Who, When, What, Why, How? API Consumers API Providers Architects App Sec Code First Individual Collaborative Is API Design just an Afterthought / Byproduct? Spec First

Slide 41

Slide 41 text

Slide 42

Slide 42 text

Slide 43

Slide 43 text

© 2025 All Rights Reserved Contract Driven Development – In a nutshell Consumer Provider API Design First • Shift Left all the way to Design • Reduced time-to-market due to Parallel Development • Enhanced DevEx with improved Collaboration • Resilient API Building Blocks