API = Some REST and HTTP, right? RIGHT?!

"API = Some REST and HTTP, right? RIGHT?!," presented by Rustam Mehmandarov from Miles, challenges common assumptions about REST APIs and explores practical patterns for building robust, maintainable APIs in real-world systems. This session was recorded at Open Community Experience 2026 (OCX26) in Brussels, Belgium, as part of the Main Track. This session examines the gap between theoretical REST principles and how APIs are implemented in practice, highlighting common pitfalls and offering production-ready approaches for building reliable API systems. It starts by revisiting REST fundamentals, including HTTP semantics, error handling, and API contracts, and shows how many so-called REST APIs diverge from these principles in real-world implementations. Particular attention is given to incorrect use of HTTP status codes and inconsistent error responses, which create fragile integrations and debugging challenges. The talk introduces practical design patterns for building better APIs, including clear endpoint structures, proper use of HTTP verbs, and consistent content negotiation. It also explores hypermedia-driven APIs, where responses include actionable links that guide clients and reduce guesswork when interacting with services. Versioning strategies are covered in depth, comparing approaches such as URL-based versioning, headers, and media types. The session also addresses API lifecycle management, including deprecation strategies, backward compatibility, and tracking usage through metrics. Documentation is treated as a core part of API design, with emphasis on annotation-driven approaches such as OpenAPI, enabling documentation to stay aligned with implementation and act as a living contract. Security considerations are discussed across multiple layers, including authentication, role-based access control, input validation, and protection against common vulnerabilities such as injection attacks. The session also references broader API security risks and best practices for safeguarding systems. Finally, the talk explores advanced patterns such as pagination, filtering, bulk operations, and asynchronous processing for long-running tasks, along with guidance on when to consider alternatives like GraphQL or gRPC depending on performance and architectural needs. Key topics covered - REST API design principles - HTTP status codes and error handling - API contracts and OpenAPI specification - hypermedia APIs and HATEOAS - API versioning strategies - API deprecation and lifecycle management - annotation-driven API documentation - API security and validation - pagination, filtering, and bulk operations - GraphQL and gRPC alternatives Why this matters APIs are the backbone of modern systems, but poor design choices create long-term maintenance and integration problems. This session focuses on practical patterns that help teams build APIs that are easier to evolve, debug, and scale. About OCX26 Open Community Experience 2026 is the Eclipse Foundation’s flagship event, held in Brussels, Belgium. It brings together developers, architects, and industry leaders to explore open source technologies across domains including IoT, AI, automotive, and security, with a focus on practical implementation and collaboration. Learn more at https://www.ocxconf.org/ Chapters 00:00 introduction and session overview 01:53 REST concepts and real-world challenges 04:12 common API design pitfalls 07:46 REST basics and HTTP semantics 11:07 error handling and HTTP status codes 12:16 API design patterns and structure 14:02 hypermedia and HATEOAS 16:17 API versioning strategies 22:13 API deprecation and lifecycle 26:20 documentation and OpenAPI 32:06 API security and best practices 36:45 advanced patterns and scalability 40:43 GraphQL and gRPC overview 44:14 conclusion and key takeaways