Software Engineering II: Web API Design                                   

                                                                   Philipp Fruck                                                                   

                                                Web Application Structure                                                 

            ██ Traditional Web Applications                                                                                                        

               •  Browser ⇄ Server ⇄ Database                                                                                                      

               •  Server Side Rendering (SSR)                                                                                                      

                  ◦  No JavaScript (JS) required                                                                                                   

                  ◦  Example: PHP, Django                                                                                                          

               •  Full page reload every time                                                                                                      

               •  State lives on server session                                                                                                    

               •  Limited interactivity                                                                                                            

                  ◦  Hard to support mobile apps                                                                                                   

               •  UI tightly coupled to backend                                                                                                    

               •  Modernization: jQuery, alpine.js, HTMX                                                                                           

                                                      Software Engineering II: Web API Design                                               2 / 31 

                                                Web Application Structure                                                 

            ██ Modern SPA Architecture                                       ██ New Problems                                                       

               •  SPA = Single Page Application                                 •  Search Engine Optimization (SEO) issues                         

               •  Initial HTML loads once                                       •  Slow first page load                                            

                  ◦  Afterwards: Dynamic updates using JS                          ◦  Large JS bundles                                             

               •  Frontend framework handles "routing"                             ◦  More client-side computation                                 

                  ◦  Often using page anchor (https://my.app/#/mypage)          •  Complex state management                                        

               •  Stateless API calls                                              ◦  More state on client, but only server state is               

               •  Often Token-based auth (JWT, OAuth)                                 really persistent                                            

               •  Decoupled frontend/backend                                    •  API overfetching                                                

                  ◦  Often different development teams                                                                                             

                                                      Software Engineering II: Web API Design                                               3 / 31 

                                                Web Application Structure                                                 

            ██ Modern Full-Stack Frameworks                                  ██ Hydration Flow                                                     

               •  Combine SSR with interactivity                                                                                                   

               •  Examples: Next.js/Nuxt/Remix/SvelteKit                                                                                           

               •  Enables Hydration                                                                                                                

                  ◦  Fast first paint                                                                                                              

                  ◦  Rich interactivity                                                                                                            

            Advantages:                                                                                                                            

               •  SEO-friendly                                                                                                                     

               •  Fast initial load                                                                                                                

               •  API routes built-in                                                                                                              

               •  Reduced boilerplate                                                                                                              

               •  Shared types                                                                                                                     

                                                      Software Engineering II: Web API Design                                               4 / 31 

                                                               API Styles                                                                

            ██ What is an API Style?                                         ██ Why This Matters                                                   

            An API style defines:                                            Architecture decisions here:                                          

               •  How clients communicate                                       •  affect scalability                                              

               •  How data is structured                                        •  affect performance                                              

               •  How operations are modeled                                    •  affect developer experience                                     

               •  How contracts are defined                                     •  live for years                                                  

            ▓▓▓ Today                                                                                                                              

            REST (main focus) | GraphQL | gRPC | WebSockets | SOAP (briefly)                                                                       

                                                      Software Engineering II: Web API Design                                               5 / 31 

                                                                     REST                                                                      

            Representational State Transfer                                                                                                        

            Architectural style defined by Roy Fielding                                                                                            

            ⚠️ Not just "HTTP + JSON"                                                                                                              

            ▍ https://roy.gbiv.com/pubs/dissertation/fielding_dissertation.pdf                                                                     

            Further reading (more descriptive):                                                                                                    

            ▍ O'Reilly REST API Design Rulebook                                                                                                    

                                                      Software Engineering II: Web API Design                                               6 / 31 

                                                         REST Constraints                                                          

            True REST requires:                                                                                                                    

               1. Client–Server                                                                                                                    

               2. Stateless                                                                                                                        

               3. Cacheable                                                                                                                        

               4. Uniform Interface                                                                                                                

               5. Layered System                                                                                                                   

               6. (Optional) Code on Demand                                                                                                        

            If you break these -> HTTP API, not REST.                                                                                              

                                                      Software Engineering II: Web API Design                                               7 / 31 

                                                             HTTP Methods                                                              

            Method  │ Description                                           │ Safe │ Idempotent │ Cacheable                                        

            ────────┼───────────────────────────────────────────────────────┼──────┼────────────┼──────────                                        

            HEAD    │ Same as GET but returns headers only (no body).       │ Yes  │ Yes        │ Yes                                              

            OPTIONS │ Returns supported HTTP methods for a resource (CORS). │ Yes  │ Yes        │ No                                               

            GET     │ Retrieves data from the server without modifying it.  │ Yes  │ Yes        │ Yes                                              

            POST    │ Sends data to the server to create a new resource.    │ No   │ No         │ Yes                                              

            PUT     │ Replaces an existing resource with new data.          │ No   │ Yes        │ No                                               

            PATCH   │ Partially updates an existing resource.               │ No   │ No         │ Depends                                          

            DELETE  │ Removes a resource from the server.                   │ No   │ Yes        │ No                                               

            TRACE   │ Performs a message loop-back test for diagnostics.    │ Yes  │ Yes        │ No                                               

            CONNECT │ Establishes a tunnel to the server (often for HTTPS). │ No   │ No         │ No                                               

            ▍ https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods                                                                  

                                                      Software Engineering II: Web API Design                                               8 / 31 

                                                        Uniform Interface                                                         

            In REST HTTP verbs have meaning.                                                                                                       

               •  GET     → safe, idempotent                                                                                                       

               •  POST    → create (or run controller)                                                                                             

               •  PUT     → replace                                                                                                                

               •  PATCH   → partial update                                                                                                         

               •  DELETE  → idempotent delete                                                                                                      

            CRUD = Create (POST) Read (GET) Update (PUT/PATCH) Delete (DELETE)                                                                     

            ⚠️ not just GET/POST as traditional HTML forms                                                                                         

                                                      Software Engineering II: Web API Design                                               9 / 31 

                                                 Resource-Oriented Design                                                  

            Resources are nouns. Nouns are always in plural form.                                                                                  

            ▓▓▓ Good:                                                        ▒▒▒▒ Bad:                                                             

            GET /orders/123                                                  POST /createOrder                                                     

            POST /orders                                                     POST /deleteOrder                                                     

            DELETE /orders/123                                                                                                                     

                                                      Software Engineering II: Web API Design                                              10 / 31 

                                                       Naming Conventions                                                        

            ██ Identifiers                                                                                                                         

               •  Use singular nouns for identifiers: GET /users/philipp                                                                           

               •  Use some other kind of identifier (not noun):                                                                                    

                  ◦  /users/1337                                                                                                                   

                  ◦  /users/cafe1234-coff-ee00-bean-123456789abc                                                                                   

            ██ Collections and Controllers                                                                                                         

               •  Use plural nouns for collections: GET /users                                                                                     

               •  Use verbs for controllers: POST /emails/42/resend                                                                                

                                                      Software Engineering II: Web API Design                                              11 / 31 

                                                            URI Structure                                                             

            Longer paths separated by / indicate a hierarchical relationship                                                                       

            https://api.example.com/electronics/computers/laptops                                                                                  

            Use hyphens for more readable URLs, avoid underscores                                                                                  

            https://api.example.com/philipp/lectures/introduction-to-linux/                                                                        

            Use lowercase letters and avoid file extensions                                                                                        

            E.g. Content-type: application/json header instead of api.example.com/users.json                                                       

                                                      Software Engineering II: Web API Design                                              12 / 31 

                                                             Query Design                                                              

            ██ Filtering                                                     ██ Partial Responses                                                  

            Queries can be used to filter certain resources:                    •  Imagine a user selection field                                  

                                                                                •  We send a GET /users request                                    

               •  GET /users returns all users                                  •  Now we get all Users                                            

               •  GET /users?firstname=Philipp filters the users by                ◦  First name/Last name                                         

                  first name                                                       ◦  Date of birth                                                

                                                                                   ◦  Address & Email                                              

            ██ Pagination                                                       •  But we only need name and ID!                                   

            Our APIs often serve lots of data. Use pagination for more       ⚠️ Overfetching                                                       

            responsiveness:                                                                                                                        

                                                                             Up to own implementation, e.g.                                        

               •  GET /students?pageSize=50&page=3                                                                                                 

                                                                             GET /users?fields=id,name                                             

                                                      Software Engineering II: Web API Design                                              13 / 31 

                                                        HTTP Status Codes                                                         

            ██ Status Codes Matter!                                          Status │ Description                                                  

                                                                             ───────┼───────────────────                                           

            Q: Which status codes do you know?                               200    │ OK                                                           

                                                                             201    │ Created                                                      

            Not just 200 or 500                                              204    │ No Content                                                   

                                                                             400    │ Bad Request                                                  

               •  Clients want to rely on status codes                       401    │ Unauthorized                                                 

                                                                             403    │ Forbidden                                                    

            Never return 200 with content like                               404    │ Not Found                                                    

                                                                             405    │ Method Not Allowed                                           

                                                                             409    │ Conflict                                                     

                  {"error": "Unexected error"}                               418    │ I'm a teapot                                                 

            ▍ https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status                                                                   

                                                      Software Engineering II: Web API Design                                              14 / 31 

                                                           Authentication                                                            

            REST uses token based authentication                                                                                                   

               •  Authenticate against API (Username/Password)                                                                                     

               •  Or use identity provider (OAuth)                                                                                                 

               •  User retrieves token(s)                                                                                                          

                  ◦  Access + Refresh token is possible                                                                                            

                  ◦  Can be string-token or JWT                                                                                                    

               •  Authenticate against API                                                                                                         

                  GET /api/data                                                                                                                    

                  Authorization: Bearer <access_token>                                                                                             

                                                      Software Engineering II: Web API Design                                              15 / 31 

                                                          REST Attributes                                                           

            ██ Statelessness                                                 ██ Maturity Model after Richardson                                    

            Each request contains:                                           Level   │ Description                                                 

                                                                             ────────┼──────────────────                                           

               •  Authentication                                             Level 0 │ HTTP as transport                                           

               •  Context                                                    Level 1 │ Resources                                                   

               •  All required data                                          Level 2 │ HTTP verbs                                                  

                                                                             Level 3 │ Hypermedia                                                  

            Server stores no client session.                                                                                                       

                                                                             Most APIs stop at Level 2                                             

            Benefits:                                                                                                                              

               •  Horizontal scaling                                                                                                               

               •  Simpler infrastructure                                                                                                           

                                                      Software Engineering II: Web API Design                                              16 / 31 

            ██ HATEOAS                                                                                                                             

            Hypermedia As The Engine Of Application State                                                                                          

            Example response:                                                                                                                      

                                                  {                                                                                                

                                                    "id": 123,                                                                                     

                                                    "status": "shipped",                                                                           

                                                    "_links": {                                                                                    

                                                      "self": "/orders/123",                                                                       

                                                      "cancel": "/orders/123/cancel"                                                               

                                                    }                                                                                              

                                                  }                                                                                                

            Almost nobody fully implements this...                                                                                                 

            Though e.g. AWX gets pretty close                                                                                                      

                                                      Software Engineering II: Web API Design                                              17 / 31 

                                                    Versioning Strategies                                                     

            ██ Why should we use versioning?                                 ██ Common approaches                                                  

               •  APIs evolve                                                   •  URI versioning:                                                 

               •  Clients stay static or lack behind                               ◦  api.example.com/v1/orders                                    

                  ◦  Web Apps can be distributed together                          ◦  v1.example.com/orders                                        

                  ◦  What if "old" SPA contact new backend?                     •  Header versioning                                               

                     ▪  Page reload required                                       ◦  Header: "X-API-Version: 1"                                   

                  ◦  What about native clients?                                 •  Content negotiation                                             

               •  How can old and new clients use the same API?                    ◦  Accept: application/vnd.company.v1+json                      

            ▍ Pragmatism > purity.                                                                                                                 

                                                      Software Engineering II: Web API Design                                              18 / 31 

                                                                  OpenAPI                                                                   

            ██ What                                                          ██ Why                                                                

            Machine-readable REST contract.                                  Enables:                                                              

            Describes:                                                          •  Client code generation                                          

                                                                                •  Server stub generation                                          

               •  Endpoints                                                     •  Mock servers                                                    

               •  Schemas                                                       •  Documentation                                                   

               •  Authentication                                                •  Contract-first development                                      

               •  Responses                                                                                                                        

                                                                             Single source of truth.                                               

            YAML or JSON.                                                                                                                          

            ▍ All JSON is valid YAML                                                                                                               

                                                      Software Engineering II: Web API Design                                              19 / 31 

                                                  OpenAPI Code Generation                                                   

            ██ Which direction                                               ██ Which version                                                      

            From one spec we can generate:                                      •  OpenAPI v2 ("Swagger")                                          

                                                                                •  OpenAPI v3.X                                                    

               •  API Clients/SDKs                                              •  Be as modern as possible :)                                     

               •  Server Stubs                                                     ◦  Limitation: Codegen Tooling                                  

            The spec can also be generated!                                                                                                        

               •  See e.g. FastAPI/Django REST Framework                                                                                           

                  ◦  Also available for every other relevant language/framework                                                                    

                                                      Software Engineering II: Web API Design                                              20 / 31 

                                                    OpenAPI Codegen Tools                                                     

            ██ Viewers                                                       ██ Generators                                                         

            Can be bundled with your application or used standalone to       OpenAPI Generator (https://openapi-generator.tech)                    

            view the OpenAPI spec                                                                                                                  

                                                                                •  Most popular                                                    

               •  Swagger UI (                                                  •  Clients/Servers/Docs                                            

                  https://github.com/swagger-api/swagger-ui)                                                                                       

               •  Swagger Editor (https://editor.swagger.io)                 Swagger Codegen (https://swagger.io/tools/swagger-codegen)            

               •  Redoc (https://github.com/Redocly/redoc)                                                                                         

               •  Stoplight Tools (https://github.com/stoplightio)              •  "Original" OpenAPI codegen tool                                 

                                                                                •  Less maintenance, not community driven                          

            ██ Mock Servers                                                                                                                        

                                                                             AutoRest (https://github.com/Azure/autorest)                          

            Generate static responses (no logic)                                                                                                   

                                                                                •  From Microsoft, Azure SDK Style                                 

               •  PRISM (https://github.com/stoplightio/prism)                                                                                     

                                                                             And more depending on Language/Framework                              

                                                      Software Engineering II: Web API Design                                              21 / 31 

                                                                   Events                                                                    

            REST APIs are focused on HTTP Polling                                                                                                  

            Use GET or HEAD to retrieve resource                                                                                                   

            But what if we want to get notified by the server?                                                                                     

                                                      Software Engineering II: Web API Design                                              22 / 31 

                                                               WebSockets                                                                

               •  Persistent connection – Stays open, unlike HTTP request/response.                                                                

               •  Bidirectional – Server can push data anytime; client can send anytime.                                                           

               •  Low latency – Ideal for real-time apps.                                                                                          

               •  Protocol – Starts as HTTP/HTTPS handshake, then “upgrades” to WebSocket.                                                         

               1. Client opens socket                               2. Server sends message when required                                          

              wss://example.com/socket                                       { "type": "message", "content": "Hello!" }                            

                                                      Software Engineering II: Web API Design                                              23 / 31 

                                                          Other API Types                                                           

                                                            brief summary                                                             

                                                      Software Engineering II: Web API Design                                              24 / 31 

                                                                  GraphQL                                                                   

            ██ Different philosophy                                          ██ Characteristics                                                    

            Single endpoint/method:                                             •  Strongly typed schema                                           

                                                                                •  No overfetching                                                 

               •  POST /graphql                                                 •  No underfetching                                                

                                                                                •  Typically no versioning                                         

            Client defines the shape of the response                            •  Evolving schema                                                 

            Supports subscriptions -> Push Events                                                                                                  

                                                      Software Engineering II: Web API Design                                              25 / 31 

                                                          GraphQL Example                                                           

            Example Query body:                          Client controls data selection -> Like SQL for the frontend                               

                                                            •  Avoids complicated backend logic when filtering/joining data                        

               1 query {                                    •  Avoids overfetching of data                                                         

               2     order(id: 123) {                                                                                                              

               3         id                                                                                                                        

               4         status                                                                                                                    

               5         items {                                                                                                                   

               6             name                                                                                                                  

               7             price                                                                                                                 

               8         }                                                                                                                         

               9     }                                                                                                                             

              10 }                                                                                                                                 

                                                      Software Engineering II: Web API Design                                              26 / 31 

                                                         GraphQL Contract                                                          

            Schema Definition Language (SDL):                                From schema you can generate:                                         

                                                                                •  Typed clients                                                   

                  type Order {                                                  •  Models/Interfaces for different programming                     

                      id: ID!                                                      languages                                                       

                      status: String!                                                                                                              

                  }                                                          Very strong tooling ecosystem.                                        

            Low effort to try out! For Postgres: Try pg_graphql / graphile / hasura                                                                

               •  Instantly make your database a GraphQL server                                                                                    

                  ◦  ⚠️ Only expose the tables you want, don't leak data!                                                                          

                                                      Software Engineering II: Web API Design                                              27 / 31 

                                                                     gRPC                                                                      

               •  High-Performance Remote Procedure Call (RPC) interface                                                                           

               •  Protocol Buffers (Protobuf) – compact binary serialization format                                                                

               •  HTTP/2 – supports multiplexing, bidirectional streaming, and low latency                                                         

               •  Strongly typed contracts via .proto files                                                                                        

                                              service UserService {                                                                                

                                                  rpc GetUser (UserRequest) returns (UserResponse);                                                

                                              }                                                                                                    

               •  More for Server-Side API queries                                                                                                 

               •  Browsers need gRPC-Web (cannot open raw HTTP/2 streams)                                                                          

               •  .proto files can be used for codegen                                                                                             

                                                      Software Engineering II: Web API Design                                              28 / 31 

                                     SOAP (Simple Object Access Protocol)                                      

               •  XML-based protocol. Not just HTTP; can run over SMTP, TCP, etc                                                                   

               •  Uses WSDL (Web Services Description Language) contracts                                                                          

               •  Uses RPCs based on dynamic XML content:                                                                                          

                                      1 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">                                       

                                      2   <soap:Header>                                                                                            

                                      3     <!-- Optional metadata -->                                                                             

                                      4   </soap:Header>                                                                                           

                                      5   <soap:Body>                                                                                              

                                      6     <m:GetUser xmlns:m="http://example.com/users">                                                         

                                      7       <m:UserId>123</m:UserId>                                                                             

                                      8     </m:GetUser>                                                                                           

                                      9   </soap:Body>                                                                                             

                                     10 </soap:Envelope>                                                                                           

               •  TL;DR: Not as simple as the name implies, rather complex and bloated                                                             

                                                      Software Engineering II: Web API Design                                              29 / 31 

                                                                    TL;DR                                                                     

            Use REST when:                               Use GraphQL when:                        Use gRPC when:                                   

               •  Public APIs                               •  Many frontend variants                •  Internal microservices                     

               •  External consumers                        •  Complex data graphs                   •  Performance critical                       

               •  Simplicity matters                        •  Avoiding overfetching is              •  Strong contracts required                  

               •  Browser-first                                critical                                                                            

            Use SOAP when: The application already exists, and you don't have a choice                                                             

                                                      Software Engineering II: Web API Design                                              30 / 31 

                                            Thank you for your attention!                                             

                                                Don't forget the feedback                                                 

                                                      Software Engineering II: Web API Design                                              31 / 31