API Design Guidelines Mike Kistler & Dan Hudlow IBM Cloud - - PowerPoint PPT Presentation

▶
api design guidelines
SMART_READER_LITE
LIVE PREVIEW

API Design Guidelines Mike Kistler & Dan Hudlow IBM Cloud - - PowerPoint PPT Presentation

Feb 27, 2023 105 likes •399 views

API Design Guidelines Mike Kistler & Dan Hudlow IBM Cloud Developer Experience Why you need API Design Guidelines Consistency in your API design will benefit your users will benefit your service/library/tool developers 2

slide-1
SLIDE 1

API Design Guidelines

Mike Kistler & Dan Hudlow IBM Cloud Developer Experience

slide-2
SLIDE 2

Why you need API Design Guidelines

  • Consistency in your API design
  • will benefit your users
  • will benefit your service/library/tool developers

2

slide-3
SLIDE 3

Guiding Principles

  • Usefulness
  • Adherence to HTTP semantics
  • Ease of use and low barrier to entry
  • Defensiveness/Compatibility
  • Security
  • Longevity

3

slide-4
SLIDE 4

References

  • Microsoft API Guidelines

https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md

  • Google API Guidelines

https://cloud.google.com/apis/design/

  • API Stylebook

http://apistylebook.com/design/guidelines/

4

slide-5
SLIDE 5

Design First

  • User stories
  • ERDs
  • and UML

5

slide-6
SLIDE 6

Specification Format

  • OpenAPI

http://spec.openapis.org/oas/v3.0.2

  • r

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

  • Linux Foundation project (Open)
  • Specifically OpenAPI v3.x
  • published July 2017

6

slide-7
SLIDE 7

Resource-oriented API design

7

  • API consists of nouns — resources — and verbs — operations
  • Final static segment in API path is the resource name
  • Always plural
  • Resource instances have a unique ID
  • Resource has a well defined schema of its contents
slide-8
SLIDE 8

Example Resource

/authors/18345 { “id”: 18345, “first_name”: “Scott”, “last_name”: “Thompson”, “city”: “Dallas”, “region”: “Texas”, “country”: “United States”, “tags”: [“Objective-C”, “Swift”, “Ruby”], “href”: “https://api.hudlow.org/authors/18345” }

8

slide-9
SLIDE 9

Resource Format

  • JSON
  • JSON is unordered
  • JSON names are case-sensitive
  • But not any JSON
  • Use well-defined types
  • Don’t mix types within an array
  • Beware of "null"
  • Create clear guidelines about what is/is not allowed

9

slide-10
SLIDE 10

Naming Conventions

  • snake_case
  • camelCase
  • UpperCamelCase
  • Kebab-case

10

slide-11
SLIDE 11

Naming Conventions

  • snake_case
  • Our choice for parameter and property names
  • camelCase
  • Our choice for operation ids
  • UpperCamelCase
  • Our choice for schema names
  • kebab-case

11

slide-12
SLIDE 12

12

C R U D

Update Create Read Delete

Operations

slide-13
SLIDE 13

13

C R U D

Update with PATCH Create with POST Read with GET Delete with DELETE

Operations

slide-14
SLIDE 14

14

C R U D

Create and Update with POST Read with GET Delete with DELETE

Operations

slide-15
SLIDE 15

15

HTTP Methods

slide-16
SLIDE 16

GET & HEAD

  • Safe
  • Idempotent
  • Ignore request bodies

16

slide-17
SLIDE 17

POST

  • Unsafe
  • Non-idempotent
  • Used for creation of subordinate resources:

POST /books → /books/38573

  • May also be used for modifying an existing resource:

POST /books/38573

17

slide-18
SLIDE 18

PATCH

  • Unsafe
  • Non-idempotent
  • Modify an existing resource

18

slide-19
SLIDE 19

PUT

  • Unsafe
  • Idempotent
  • Used for creating or replacing a resource at a known URL

19

slide-20
SLIDE 20

Standard Error Model

400 Bad Request { “code”: “missing_field”, “message”: “The `first_name` field is needed to create an author.”, “target”: { “type”: “field”, “name”: “first_name” } }

20

slide-21
SLIDE 21

Programmatic Information in Errors

400 Bad Request { “code”: “missing_field”, “message”: “The `first_name` field is needed to create an author.”, “target”: { “type”: “field”, “name”: “first_name” } }

21

slide-22
SLIDE 22

Collections

GET /authors { “authors”: [ { “id”: 18345, “first_name”: “Scott”, “last_name”: “Thompson”, “href”: “https://api.hudlow.org/authors/18345” }, { “id”: 63840, “first_name”: “David”, “last_name”: “Gelphman”, “href”: “https://api.hudlow.org/authors/63840” } ] }

22

slide-23
SLIDE 23

Offset & Limit Pagination

GET /authors?offset=4&limit=2

{ “total_count”: 12 “authors”: [ { “id”: 18345, “first_name”: “Scott”, “last_name”: “Thompson”, “href”: “https://api.hudlow.org/authors/18345” }, { “id”: 63840, “first_name”: “David”, “last_name”: “Gelphman”, “href”: “https://api.hudlow.org/authors/63840” } ] }

23

slide-24
SLIDE 24

Token-based Pagination

GET /authors { “total_count”: 12 “next”: { “token”: “d537748fe4” }, “authors”: [ { “id”: 18345, “first_name”: “Scott”, “last_name”: “Thompson”, “href”: “https://api.hudlow.org/authors/18345” }, { “id”: 63840, “first_name”: “David”, “last_name”: “Gelphman”, “href”: “https://api.hudlow.org/authors/63840” } ] }

24

slide-25
SLIDE 25

Pagination

  • Offset and limit pagination
  • Stateless
  • Imprecise
  • Token-based pagination
  • Robust
  • More difficult and demanding to implement
  • Stateful vs stateless considerations


25

slide-26
SLIDE 26

26

Versioning

slide-27
SLIDE 27

Compatibility

  • Usually compatible
  • Adding new fields to models
  • Adding new types of resources at new URLs
  • Usually incompatible
  • Removing resource types
  • Removing fields from resources
  • Adding new required fields to templates
  • Making previously valid field values invalid

27

slide-28
SLIDE 28

Specifying Versions

  • Custom header

API-Version: 3

  • Query parameter

/books?api_version=3

  • Content type

Accept: application/vnd.github.v3+json

  • Root path

/v3/books

28

slide-29
SLIDE 29

Go Forth

  • Define your principles and priorities
  • Create purposeful guidelines
  • Write them down
  • Start designing better web APIs

29