How can you design a RESTful software system?

Before diving deep into REST-API best practices design, I encourage you to take a step back and consider whether we can model the interaction between services using a representation of a business entity. I would ask whether the operations involve a single resource and a clear hierarchy of resources or are complex. I may consider using RPC such as gRPC in cases where the interaction is more complex and cannot be clearly mapped to a single resource

Things I'm wary of when designing a RESTful system: Domain-Driven Focus: Align APIs with the domain for better clarity. OpenAPI Docs: Use OpenAPI for clear, maintainable contracts. Rate Limit Sync APIs: Protect synchronous endpoints from overload. Clear Inter-service Comms: Define API interactions with external systems precisely. Security & API Versioning: Secure from the start and plan for smooth API evolution. Performance with Monitoring: Leverage caching and stateless design, and ensure robust monitoring. Ensuring these help us build a near future-proof RESTful architecture.

Designing a RESTful software system involves key principles: 1) Use HTTP methods (GET, POST, PUT, DELETE) for actions on resources, 2) Employ unique URIs for each resource, 3) Ensure statelessness, no client context saved on the server, 4) Transfer data using standard formats (JSON, XML), and 5) Support HATEOAS, enabling clients to dynamically navigate the system. This approach fosters scalability, simplicity, and interoperability, ensuring effective communication between clients and servers. #RESTfulDesign #SoftwareDevelopment #APIs

1. Comprehending the Domain and Requirements: The primary focus is on deeply understanding the business context and the specific needs of stakeholders. 2. Developing Tailored Endpoints: Endpoints should be well-defined, intuitive, and closely aligned with the underlying business logic. 3. Implementing Idempotent Calls for Consistency: Idempotent calls maintain data integrity and prevent unintended side effects. 4. Establishing a Robust Security Layer: Security takes precedence. Implementing stringent security measures is essential. 5. Standardizing Error Handling: Employing suitable error codes and structure benefits both developers and end-users. It aids in promptly identifying and resolving issues.

Well this is a very relative topic! First the customers expect, which usually includes functionality and data to be accessible from any device. Enterprises are all at different stages in their API strategy roadmap, in terms of industries. And when it comes to security infrastructures, which are vary based on their API maturity, yet the tricky matter is: whether you have an API department with 60 developers and hundreds of live apps or are just starting out-the tools you use for your API security strategy should look the same. 

The first step is to identify the entities and to name your resources correctly, using precise, concise plural nouns that define their function. Use "users," "products," or "items." Bad Examples: /getAllProducts // Get all products /getProductById/1234 // Get Product with ID: 1234 /createProduct //POST: Create a product Good Examples: /products //GET: Get all products /products/1234 //GET: Get Product with ID: 1234 /products //POST: Create a product Optional Parameters: - Filtering resources: filter resources based on attributes "/products?type=retail". - Sorting results: "/products?sort=price-asc". - Paginating results: "/products?page=5&per_page=50".

Over the years, various attempts have been undertaken to establish a standard for API descriptions, with OAS now widely recognized as the prevailing standard. It is crucial for enterprises to introduce appropriate tools aimed at standardizing API design across the entire organization. During the API design process, designers should prioritize usability and granularity without compromising the potential for monetization. A coarse-grained API may divulge excessive information, while a fine-grained one might provide insufficient data. It's imperative to view API design not merely as a technical task but as a collaborative business initiative, a means of enhancing the enterprise's financial performance.

In my experience start with key entities, actors and their relationships. Use the HTTP standard methods for CRUD operations like GET, PUT, POST, PATCH, DELETE. Query parameters should be used with GET for sorting, paginations and use the RESOURCES ID in URI patterns like GET /entity/:entity_id

I really like how a good design of RESTful APIs, as outlined in these principles enhances the clarity and consistency of the API ecosystem.

Open api specifications are the industrial standart for designing restful systems. It helps you to design a well structured and documented api system.

Nothing really to define here, HTTP verb usage is rather well defined in REST and one should not deviate from the rules. Just understand the rules for verb usage and go with it: retrieving an object? it's a GET creating an object? it's a POST updating an object? it's a PUT or a PATCH deleting an object? it's a DELETE

The HTTP verbs are a great start but sometimes you will need more than just the CRUD type semantics HTTP provides. For example, suppose you have two Resources with independent life - cycles, you can link them or unlink them. For this you may need URL conventions that go beyond HTTP verbs.

Go for Dot net core API with minimal development and put micro services on the top of it. You can also implement below: 1. Interface 2. Singleton 3. Caching etc

Consider also that you have ‘safe’ methods, such as GET, HEAD, and OPTIONS. These are intended for read-only operations and should not modify the state of the system. Then there are ‘unsafe’ methods, like POST, PUT, DELETE, and PATCH. These are usually expected to modify the state of the system. Out of these, PUT and DELETE are also defined as idempotent, meaning repeating the same request should result in the same system state. Ideally, most operations are idempotent, because it allows clients to retry the operations without any special handling. Creation is often difficult to make idempotent, but things like changing a name or state should be achievable.

The popularity of RESTful APIs stems from their innate capability to define auethorized actions on a representation of data. It's imperative to uphold strict compliance with HTTP standards during the method definition process. Although there may be a temptation to mix PUT and PATCH methods, both used for update, it's essential to distinguish between them. The object representation must always be accessible through a GET method that consistently yields multiple such items. An extended URL pattern that specifically identifies an ID is the optimal choice. Additionally, filter parameters should be made available to refine the search results. The POST method should be exclusively employed for creating new resources and never for updating them.

While designing the API using appropriate design principles is must, we should also consider key aspects like security, observability, layers, versioning, tracing, patterns (RESTful, GraphQL, Falcor, RPC, HATEAOS), data format, lifecycle, governance, open API standards and automation testing.

In my perspective, the choice of representations is a pivotal aspect of RESTful API design. Opt for JSON where lightweight and human-readable formats are necessary, especially for complex data structures. XML can be beneficial for systems that require rigorous structure, validation, and namespace support. HTML is useful for responses intended for direct display in web browsers. Implement content negotiation through the Accept and Content-Type headers to allow clients to request their preferred format. Also, utilize Content-Length and ETag headers to manage response size and resource versioning, aiding in efficient caching and synchronization of data. These considerations are essential for a robust and flexible RESTful API.

Versioning of Api. HTTP Header support with additional information. Format of the content shoul be defined/documented properly that may be structured/unstructured. Error handling need to be meaningful and standard response format. Choose which suits your solution JSON XML HTML or do we need support all as required?

The selection of the right representations is crucial. Well-designed representations facilitate API evolution without disrupting existing clients. Efficient representations optimize data transfer, reducing bandwidth usage. Clear field names and data types in the representation help clients interpret the information. Careful representation design prevents exposure of sensitive data. Properly designed representations support caching strategies, reducing server load. Content negotiation allows clients to request preferred representations. Supporting various representations accommodates different client types, such as web browsers, mobile apps, and IoT devices. This ensures a consistent user experience across platforms.

Speak the language that the other side can understand. It's imperative to communicate the state and metadata of resources by adhering to principles like self-explanatory, standardized formats (JSON, XML, HTML), and content negotiation. In addition to the representation format itself, other HTTP headers, such as Content-Length and ETag, can be used to indicate the size and version of the representation, enabling clients to efficiently manage and cache resources.

Level 3, that incorporates HATEOAS, is the most advanced and fully RESTful level. It is a design that includes hypermedia controls in API responses, allowing clients to dynamically discover and navigate available resources and actions. Most RESTful web services stop at Level 2, however achieving Level 3 can provide significant benefits in terms of decoupling and adaptability. In specifically Investment Banking context, Financial institutions must carefully consider the trade-offs and assess whether the pros of HATEOAS outweigh below cons in particular context. 1. Increased complexity and unpredictability 2. Regulator compliance 3. Cyber threats 4. Overhead impacting high performance, low latency apps 5. Legacy system integrations

• Use versioning for your API. This will allow you to make changes to your API without breaking existing clients. There are a few different ways to implement versioning, such as using path parameters, query parameters, or headers. • Use pagination for large collections of resources. This will prevent the client from having to download a large amount of data at once. You can use query parameters to specify the page size and the page number. • Use rate limiting to prevent clients from overloading your server. This can be done by setting a limit on the number of requests that a client can make within a certain period of time. • Use caching to improve performance. • Monitor your API usage.

For many APIs, achieving Richardson Maturity Model level 3 is not feasible, because it requires hypermedia controls. Trying to model hypermedia controls in one of the typical API representation formats (this seems to have converged on JSON or Protobuf) will likely not be worth the effort it would take, compared to just returning a true hypermedia such as HTML.

In my experience, implementing design patterns in RESTful systems enhances their quality and usability. ROCA suggests favoring HTML for resource representation, ensuring accessibility and simplicity. HATEOAS, a principle where responses contain hyperlinks to other resources, enables better discoverability and navigation of APIs. The Richardson Maturity Model offers a graded strategy to adopt REST, with four levels - from simple HTTP use to full HATEOAS compliance. By integrating these patterns, RESTful APIs become more intuitive, scalable, and aligned with web standards, ultimately facilitating easier evolution and maintenance of the system.

Although HATEOAS, JSON:API, OData are cool in theory. It is difficult to implement plus with the release of HTTP/2 (multiplexing) do we really need these pretty things? In most cases my answer is sadly no. Having said that some sort of pattern is necessary for consistency across domain. IMHO

Before writing any code, outline the *design tenets* for the API so that all developers can follow them. You should periodically review the APIs against the tenets to ensure your API is consistent. Tenets will be specific to your API, but consider things such as: - When (or if) you will use different HTTP Verbs - What human language will the API be using? e.g. will all words be in English (and maybe US v UK?). - Will you return textual values or codes (or both) where needed? e.g an OrderStatusCode of 0 and/or an OrderStatus of 'FAILED'? - Will there be lists returned? Where there are, will there always be an index column? - In I8N important to your API and if so, what does it affect?

it is very important to have standard Error codes and status codes. Always prefer to follow HTTP status codes for each operations. Like use HTTP 200 status code for successful operations and HTTP 400 for API errors. Further response from API should give more details like error code and error message specific to domain along with HTTP status codes.

Implement authenticatiin and Authorization. Filtering for large content. Unit , integration, load testing. API documentation. Gather feedback and improve

Cross-cutting concerns in REST design are aspects of an application that affect multiple components and features throughout the system. These concerns are not tied to a specific resource or endpoint but instead "cut across" the various parts of the application. They play a crucial role in the overall design and functionality of a RESTful system for several reasons. e.g. Security Logging and Monitoring Performance Transaction Management Error Handling Scalability Compliance and Governance This often include authentication, authorization, caching, logging, error handling, security, and performance optimization. Addressing these concerns in a consistent and modular way is essential for creating a robust and reliable RESTful system.

Other things to consider: * How are you going to test them? Spock is excellent * How are you going to get consistent looking APIs across your organisation? This is really difficult as there are so many things you can do with an API. Make clear your API standards and govern them. * How can you avoid breaking changes? e.g. don't ever have arrays as top level responses because if you want to add an attribute that refers to the total payload you can't. * Follow Postel's law when you can. * Do you need more advanced things? e.g. optimistic locking for stateless APIs is non-trivial.