> Markdown version of [/videos/1675-api-some-rest-and-http-right-right](https://www.wearedevelopers.com/videos/1675-api-some-rest-and-http-right-right). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

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

Building robust REST APIs requires far more than just returning JSON. Master advanced versioning strategies, correct status codes, and OpenAPI contracts to bulletproof your enterprise architectures.

- **Speakers:** [Rustam Mehmandarov](https://www.wearedevelopers.com/@rustam-mehmandarov)
- **Event:** World Congress 2025
- **Published:** August 20, 2025
- **Duration:** 27:25
- **URL:** https://www.wearedevelopers.com/videos/1675-api-some-rest-and-http-right-right

## Summary

The presentation explores the evolution and best practices of API development, contrasting the verbose, file-driven era of SOAP and XML with modern REST paradigms. While frameworks like Jakarta EE and Spring Boot have dramatically simplified client generation and JSON serialization, developers still face fundamental structural challenges in designing, maintaining, and scaling RESTful systems.

Architectural rigor is essential for robust API design, beginning with the correct semantic use of HTTP status codes over generic 500 server errors. The discussion details multiple API versioning strategies—ranging from common URI path variables to custom headers and media types—and highlights the importance of graceful endpoint deprecation using HTTP redirects and warning headers. To guarantee long-term maintainability, the speaker stresses the absolute necessity of auto-generating living documentation via the OpenAPI specification, warning that manually written contract pages inevitably fall out of sync with the underlying codebase.

Security and performance optimization dictate production readiness, requiring standardized integrations like JWT authentication, role-based access control (RBAC), and precise CORS configuration. For high-traffic systems, developers must move beyond basic functionality by adopting advanced access patterns such as pagination, offset-based sorting, batch data processing to reduce HTTP overhead, and asynchronous handling of long-running tasks via `202 Accepted` statuses. Crucially, the speaker notes that client-facing endpoints should always abstract away internal domain structures, and engineering teams should proactively evaluate alternatives like gRPC or GraphQL when REST conventions limit their operational performance.

**Keywords:** API development best practices, REST vs SOAP architecture, JSON serialization, HTTP status codes, API versioning strategies, endpoint deprecation methods, OpenAPI specification, auto-generated contract documentation, JWT authentication, role-based access control, CORS configuration, HATEOAS implementation, REST pagination and sorting, bulk API requests, asynchronous API operations, gRPC performance, GraphQL data querying

## Chapters

1. **Introduction to application programming interfaces and maintenance challenges** (00:05) — Understanding the constant need to properly construct and maintain application programming interfaces over time.
1. **Challenges and limitations of using SOAP for API integrations** (01:55) — Early system contracts relied on verbose XML envelopes and confusing auto-generated code that hindered developers.
1. **Simplifying integrations with modern REST clients and serialization tools** (05:09) — Modern frameworks simplify endpoint mapping and automatically serialize payload data to eliminate manual parsing logic.
1. **Handling HTTP status codes correctly in REST API responses** (06:17) — Returning appropriate status codes prevents confusing generic server errors and improves the overall client debugging experience.
1. **Implementing REST methods and content negotiation in Java frameworks** (08:04) — Defining endpoints with specific HTTP verbs and media types enables predictable server request routing and payload formatting.
1. **Enhancing application navigation with hypermedia as the engine** (09:37) — Adding structured reference links inside API responses allows clients to dynamically discover and navigate available endpoint actions.
1. **Strategies for versioning application programming interfaces consistently and effectively** (10:45) — Managing API configurations through URL paths, custom application headers, or content media types ensures smooth client transitions.
1. **Managing endpoint deprecation and tracking legacy API usage metrics** (14:11) — Providing clear redirect network paths and monitoring access metrics helps teams safely retire old software API versions.
1. **Automating open API specifications for living digital documentation contracts** (16:17) — Generating service specifications directly from code annotations maintains an accurate and easily accessible digital API contract framework.
1. **Securing REST APIs with JSON tokens and role access** (19:19) — Implementing robust authentication token validation and explicit endpoint roles protects data against unauthorized access and unvalidated cross-origin requests.
1. **Implementing API pagination and sorting for optimized payload delivery** (21:50) — Using database query offsets and dynamic sorting parameters helps teams efficiently manage large datasets without overwhelming downstream clients.
1. **Handling long running operations using asynchronous REST endpoint responses** (23:07) — Returning an accepted HTTP status alongside a temporary polling resource location prevents congested background server processing queues.
1. **Optimizing high volume integrations using bulk batch API operations** (24:21) — Sending a large batch of objects within a single network HTTP request drastically reduces repetitive application authentication overhead.
1. **Exploring alternative data retrieval methods beyond standard REST patterns** (25:23) — Modern technologies like binary gRPC connections and flexible GraphQL queries offer high-performance networking alternatives specifically tailored for advanced domain models.

## Related Moments

- [Evolution of API interfaces toward declarative data fetching](https://www.wearedevelopers.com/videos/1054-graphql-does-it-replace-sql-rest-or-something-else) (from "GraphQL: Does it replace SQL, REST or Something Else?")
- [Evaluating benefits and drawbacks of common API formats](https://www.wearedevelopers.com/videos/1195-the-great-api-debate-rest-graphql-or-grpc) (from "The Great API Debate: REST, GraphQL, or gRPC?")
- [The enduring legacy of REST APIs](https://www.wearedevelopers.com/videos/1683-rest-in-peace-what-does-the-api-protocol-of-the-future-look-like-or-do-we-have-it-already) (from "REST in Peace? What does the API protocol of the future look like? Or do we have it already?")
- [Defining REST APIs and software development anti-patterns](https://www.wearedevelopers.com/videos/100208-rest-api-antipatterns) (from "Rest API Antipatterns")
- [Choosing the right API protocol today](https://www.wearedevelopers.com/videos/1683-rest-in-peace-what-does-the-api-protocol-of-the-future-look-like-or-do-we-have-it-already) (from "REST in Peace? What does the API protocol of the future look like? Or do we have it already?")
- [Common errors in REST API design and documentation](https://www.wearedevelopers.com/videos/100208-rest-api-antipatterns) (from "Rest API Antipatterns")

## Related Articles

- [Exploring AI: Opportunities and Risks for Developers](https://www.wearedevelopers.com/magazine/522-exploring-ai-opportunities-and-risks-for-developers)
- [The CAMARA Project: How Telcos Collaborating Improves Developer Experience](https://www.wearedevelopers.com/magazine/671-the-camara-project-how-telcos-collaborating-improves-developer-experience)
- [The Web We Broke (And Why AI Agents Are Paying the Price) - AgentCon Berlin](https://www.wearedevelopers.com/magazine/735-the-web-we-broke-and-why-ai-agents-are-paying-the-price-agentcon-berlin)
- [Dev Digest 139 - Soft and hard queries](https://www.wearedevelopers.com/magazine/487-dev-digest-139-soft-and-hard-queries)

## Related Jobs

- [Staff Software Engineer](https://www.wearedevelopers.com/jobs/ext/1425755-staff-software-engineer) at **GitHub**
- [Senior Software Engineer, Client Apps Platform](https://www.wearedevelopers.com/jobs/ext/1773893-senior-software-engineer-client-apps-platform) at **GitHub**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/115163-principal-software-engineer) at **Twilio**
- [Software Engineer](https://www.wearedevelopers.com/jobs/ext/1304791-software-engineer) at **Bitpanda**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/146806-principal-software-engineer) at **Twilio**
- [Principal Software Engineer](https://www.wearedevelopers.com/jobs/ext/267591-principal-software-engineer) at **Twilio**