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. 

Understanding the domain is the key for designing software systems. Always focus on the necessary requirements and always keep it simple. DDD will help you to keep your design simple and efficient.

When I design a REST API, I give an important consideration to documentation, naming conventions, security and exception handling concepts.

To design a RESTful software system, define your resources, use standard HTTP methods for CRUD operations, create meaningful URIs for these resources, maintain statelessness, utilize appropriate HTTP status codes for responses, include hypermedia links for client guidance, and support content negotiation for response formats. Ensure security through authentication and authorization mechanisms, version your API for backward compatibility, implement caching for performance, provide comprehensive documentation, thoroughly test, and continuously follow REST best practices to create a scalable and well-documented system.

The domain is the foundation upon which software design is built. Creating software that meets real-world requirements is not the way to go without a thorough understanding of the domain. DDD is a well-established approach in software engineering that emphasizes modeling the domain and aligning software with it. However, there are other methodologies, principles, and architectural patterns that are widely used and considered best practices to design and develop REST API contracts.

This should follow the micro-service design paradigm. Granular units should be enabled as REST APIs, and should be driven by business functionality. One REST API endpoint can combine invocation of multiple AI ML Models / multiple REST APIs, but must achieve a logical business function within a standard response time. Error handling and Error logging is of utmost importance, and if the need be, load testing under concurrent load.

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 "https://accionvegana.org/accio/0ITbvNmLulGZltmbpxmL3d3d6MHc0/products?type=retail". - Sorting results: "https://accionvegana.org/accio/0ITbvNmLulGZltmbpxmL3d3d6MHc0/products?sort=price-asc". - Paginating results: "https://accionvegana.org/accio/0ITbvNmLulGZltmbpxmL3d3d6MHc0/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.

Designing a resource is important step for any REST API. It should represent the domain and consumers should be able to understand API capability easily. There are few basic principles which API designer should adhere to while designing the resource, some of these examples include name, selection of path vs query parameter, API version, resource path. These principles plays a huge role when you are defining public APIs and going for API as-a-service model.

Even though it isn't called out in the Fielding dissertation, I think you need a more specific definition for a Resource. For example, yes it has to be a noun but it also has to be a useful noun and a noun that is useful on its own. Otherwise you end up with very chatty API's. So for example , the Address resource should give you the zip code, the country code , the full street address everything you need so that you don't need to make another request. It shouldn't just be partial information that necessitates another request before you have anything useful.

In my experience, designing RESTful resources requires thoughtful naming and structuring to accurately represent the domain. Use nouns for resource names, like /customers for collections and /customers/123 for individual entities, avoiding verbs which are actions, not resources. Reflect hierarchy in paths, for instance, /customers/123/orders for a user's orders. Use query parameters for filtering, such as /customers?status=active. Choose meaningful identifiers for resources, like slugs /products/apple-iphone-12 instead of opaque IDs. This clarity and consistency in resource design are pivotal for an intuitive API.

Formulatation of the resources carefully is the key thing here. Those shoul be meaningful. add/update/fetch for a resource need to be easy, generic and flexible along with query parameters.

The next steps is to design the resources, where you define the various objects, data, or services that your API will expose. Resources are the core building blocks of a RESTful API, and they represent the entities or concepts that your API manages. Each resource should have a unique and meaningful identifier (usually expressed as a URI). Resource names should be nouns or noun phrases. i.e: "users,""comments" and avoid verbs in resource names like /getCustomer. Use URIs hierarchically to represent relationships between resources. i.e: /users/123/orders represents the orders of a specific user. Choose resource names that are meaningful and self-explanatory, making it easier for clients to understand the purpose of each resource.

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.

In my experience, clearly defining methods is key to a functional RESTful API. Adhere to HTTP method semantics: use GET for fetching resources, ensuring it's safe and idempotent, meaning multiple requests have the same effect as one. Employ POST for creating resources or triggering state changes, and it’s not idempotent, which means subsequent identical requests may have different effects. Use PUT for idempotent full updates/replacements of resources. Opt for PATCH for non-idempotent partial updates. Finally, DELETE should be used for removing resources, and it should be idempotent. This standardized approach streamlines client interactions with your API.

Each request should contain all necessary information for stateless implementation. PUT, POST, DELETE GET must have all information and server need not to store anything

The 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.

GET: Retrieve information about a resource or a collection. POST: Create a new resource or perform a non-idempotent operation. PUT or PATCH: Update an existing resource with PUT usually for full updates and PATCH for partial updates. DELETE: Remove a resource.

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.

Choosing representations in a RESTful API involves determining the format in which data will be exchanged between clients and the server. Common representation formats include JSON and XML. The chosen representation should align with the preferences and requirements of the application and its users. Additionally, consider providing support for content negotiation, allowing clients to request a specific representation format based on their needs. This flexibility ensures that the API can cater to a variety of clients with different capabilities and preferences.

Representation of an API is another key factor for well designed systems. Again open api specification is industrial standarts here. Follow the rules and you will have a well designed api system. While determining the inputs and outputs, always keep it simple.

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

Take use of 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.

Applying design patterns in a RESTful API involves organizing resources and endpoints, using appropriate HTTP methods, supporting various representation formats, and implementing patterns such as pagination, HATEOAS, and caching for improved performance and maintainability. Careful consideration of specific requirements, like versioning and security, ensures the API adheres to best practices and effectively addresses the needs of the system and its users.

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.

In addition to design patterns, prioritize clear documentation, robust error handling, and thorough testing for your RESTful API. Ensure scalability, implement strong security measures, and monitor usage for insights. Consider community feedback and implement features like rate limiting to enhance the overall developer experience.

Domain-Driven Focus: It is crucial to maintain a domain-driven approach. Naming Convention:Adopt a naming convention that emphasises nouns when defining URIs. OpenAPI Docs: Utilize the OpenAPI specification. Communication Channel: Clearly define the communication protocol . Rate Limiting and Back Pressure: Implement effective strategies for handling overload situations. Logging/Error Handling: Prioritise error handling and logging Performance Optimization: Implement caching, pagination strategies. Deployment Strategy and CI/CD Pipeline: Monitoring: keep track of key metrics and ensure the observability of the API. Security and API Versioning:Prioritise security from the initial stages and plan for seamless API evolution.

Adopt a layered architecture for modularity and maintainability. Enforce a uniform interface using standard HTTP methods and consistent resource naming. Organize endpoints around resources and utilize HATEOAS for self-discovery. Implement caching, versioning, error handling, security, and monitoring for optimal performance and reliability.

Also the important aspects 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.

There are few basic things that you should consider before starting with the API development. 1. how are the APIs going to be utilised, are these going to be public or private. Authentication and Rate Limiting could then become very important for public APIs. 2. Organising your resources in the API could also be very important ensure the sub-resources are optimally aligned like having all customer details under /customer/getAddress, /customer/getOrderHistory and product details under /product/getProductDetails, product/getProductImages. Sometimes these basic things are missed and can lead to dissatisfied API clients. 3. Error handling, handle errors and ensure you provide some information wherever possible for any errors that occur.