I am writing a WS and I am building the architecture but I have some questions.
For example, my front application need to fetch a list of users. Each user have a list of accounts, authorizations, capabilities. I am displaying a this list of users and when I click on a specific user, I would like to display his details (list of accounts, authorizations, capabilities).
So what is the best way to architect my WS?
In my opinion, I will make first an endpoint to get a list of user (simple just with id and name).
When I click on detail, I call another endpoint to get user detail.
But should I have to separate list of accounts, list of authorizations, list of capabilities in 3 endpoints (one per functionality). Each one become reusable. Or should I call a single endpoint that return all informations?
What are the best practices in SOA?
So just using REST/SOAP services does not make your architecture SOA.SOA is an architectural style and set of disciplines and principles that can be implemented regardless of the underlying technology base.
How to design SOA services? Well the answer is really that this is decided in your SOA governance. WIthout governance SOA soon turns into a mess. So governance contrary to popular believe is not a set of restrictive rules on how to design your services, it defines a set of best practises and disciplines that you enforce to ensure maximum success of your solution.
SOA governance helps you make decisions during design and runtime. You mentioned you have SOA governance so what does your governance dictate.I would strongly suggest separate endpoint. Single responsibility principle is important.
A singular endpoint returning everything is going to be a pain to code, pain to maintain, pain to modify while being easy to call.
Related
I have 2 years in the IT industry,i love to read a lot ,but when i go deep in some subjects i see a lot of contradiction in somes articles,forum or terms that are used interchangeable.
I understand the difference between Soap and Rest.
When we want to communicate between backends, we can use either of these 2 approaches, each with its advantages and disadvantages.
Situation :
If i have an application, which can be monolithic or not, where I have a backend and I will only have a front end that consumes it. Usually we create a Rest Api so that our front end can consume it. But we will never think about exposing our backend with Soap.(Lot of reasons)
Questions:
1 -Is it okay if I say that Rest , in addition to allowing us to exchange information between application and application (backend to backend ), is it also useful when exposing services for our front end? And SOAP is only useful for Server - Server communication?
2 -And finally, if I expose a backend only for a front end, it is ok to say that we expose a web service or conceptually we say that it is a backend for frontend ?
Question 1: No the First question is wrong Assumption. We can say that in SOAP, XML is the only means of communication, while in Rest, the accepted means is JSON, while there are other formats like XML, JSON, PDF, HTML etc. and Ofcourse, XML can be converted back from server into UI Language and XML Request deciphered at Server for a Response. So, its not Ok to say that SOAP is only for Server - Server Communication.
2. No, when you have typically exposed backend only for consumption by a Front end, you can typically say that it is a backend for numerous front end client requests. But IMO, Backend for a front end is a monolithic webapplication, both bundled in WAR. so in that sense, any UI Request can request response from the Back end web service. Hope i am able to clear your understanding about web services.
I see that in your question there are actually 4 embedded independent topics. And probably because they are always used in conjunction it is sometimes tough to understand.
I will give a short answer first:
REST and SOAP both can be used for Client-Server and Server-Server integrations. But the choice will be dependent on the questions like where you want server-side UI technology/client-side UI technology or is it a single page application/portal technology, etc.
If you expose a single-backend for a single-frontend it's technically a BFF although the term BFF is used only in the case where you have separate-backends for each type of frontend application. e.g. one for mobile, one for web, one for IoT devices, etc.
The long answer is to clarify the 4 principles. Let me give a try at this by separating the topics into the below four headings:
1. Backend(Business Layer) vs Backend for frontend(BFF)
In classical 3-tier architecture (UI-Business Layer-Database) world, the middle-layer that consists of the business and integration logic is mostly referred to as backend/business layer.
This layer can be separated from the UI/Frontend using multiple different options like APIs(REST/SOAP), RPC, Servlet Technology, etc. The limitation with this 3-tier architecture is that, it is still tightly coupled to the type of users and use-cases are limited to web/browser based. It is not a good choice when you want to reuse the business-layer for both web and mobile as the mobile applications are required to be light-weight by principle.
That's where we lean on to multi-tier architecture with Backend For Frontend(BFF) as a savior. It's just a methodology to segregate the business-layers based on consumers.
2. Monolith vs SOA vs Microservices(Optimized SOA)
In a monolith world all the code components mostly UI and Business Layer sits in a tightly coupled fashion. The simplest example would be a Java Servlet Pages(JSP) application with Java as Business Layer. These are typically server-side UI technologies.
In Service Oriented Architecture(SOA), the usecases revolve around leveraging reusable business layer functions aka services. Here one would have to deal with UI-Server, Inter-Service and Server-Server integration scenarios. It's heavily service dependent, meaning it's like a spider-web of dependent applications.
The Microservices is an extension of SOA, but the approach is to keep a resource in focus instead of services to reduce the spider-web dependencies. Hence, self-sufficient and standalone service-clusters are the base of micro-services architecture.
3. SOAP vs REST Webservices
SOAP stands for Simple Object Access Protocol, typically used by the business-layer to provide user-defined methods/services to manipulate an object. For example look at the names of the services for accessing a book collection
To get a book getABook()
Get the whole list of books listAllBooks()
Find a book by name searchABook(String name)
Update a book's details updateABookDetails()
On the other hand, REST is representational state transfer which transfers the state of a web-resource to the client using underlying existing HTTP methods. So the above services for accessing a book collection would look like
To get a book /book(HTTP GET)
Get the whole list of books /books(HTTP GET)
Find a book by name /book?name={search}(HTTP GET)
Update a book's details /book/{bookId}(HTTP PATCH/PUT)
4. How to make a correct choice of architecture?
Spot the diversity of the application user groups and usages: This will help to understand the platform(web/mobile/IoT/etc), nature of the application and session-management.
Determine the estimated/required throughput: This will help you to understand the scalability requirements.
How frequently and who will be maintaining the application: This will help to gauge the application and technology complexity, deployment cycles, deployment strategy, appetite for downtime, etc.
In conclusion, always follow the divine rule of KISS: Keep it simple, stupid.
1.)
A webapplication is for H2M communication a webservice is for M2M communication through the web. The interface of the service is more standardized, more structured, so machines can easily use it and parse the messages.
I don't think it matters where your service consumer is, it can run in a browser or it can run on the server. As long as it can communicate with the service on a relative safe channel it is ok.
You design a service usually to decouple it from multiple different consumers, so you don't have to deal with the consumer implementations. This makes sense usually when you have potentially unknown consumers programmed usually by 3rd party programmers you don't even know or want to know about. You version the service or at least the messages to stay compatible with old consumers.
If you have only a single consumer developed by you, then it might be too much extra effort to maintain a service with a quasi-standard interface. You can easily change the code of the consumer when you change the interface of the service, so thinking about interface design, standardization, backward compatibility, etc. does not make much sense. Though you can still use REST or SOAP ad hoc without much design. In this case having a RESTish CRUD API without hypermedia is a better choice I think.
2.)
I think both are good, I would say backend in your scenario.
We have different client applications (each is built with a different UI and is targeted to a different sales channels) that are used to capture orders that ultimately need to be processed by our factory.
At first we decided to offer a single "order" microservice that would be used by all these client applications for business rules execution and data storage. This microservice will also trigger our backoffice processes such as client profile update, order analysis, documents storage to our electronic vault, invoicing, communications, etc.
The challenge we are facing is that these client applications are developed by teams that are external to ours (we are a backoffice team only). Each team responsible to develop a client application will be able to offer a different UX to their users (some will allow to save orders in an incomplete state, some wil allow to capture data using a specific worflow, some will use text fields instead of listboxes for some values, etc.).
This diversity of behaviors from client applications is an issue because our microservice logic will become very complex to be able to support all those UI requirements. Moreover, everytime a change will be made to one of the client applications, we will have to modify our microservice which is a case of strong coupling.
My questions are: What would be your best advice to manage this issue? Should we let each application capture the data the way it wants (and persist it if needed in its own database) and let them call our microservice only when an order is complete and compliant to our API contract?
Should we keep our idea of having a single "order" microservice for everyone and force each client application to capture the data the same way?
Any other option?
We want to reduce the duplication of data and business rules in our ecosystem but in the same time we don't want our 'order' microservice to become a mess.
Many thanks for your help.
Moreover, everytime a change will be made to one of the client applications, we will have to modify our microservice which is a case of strong coupling.
This rings alarm bells for me. A change to a UI shouldn't require a change to a backend service. (The exception would be if a new feature were being added to a system and the backend service needed to play a part in supporting that feature, but I wouldn't just call that a change to a client.) As you have said, it's strong coupling, and that's something to be avoided in a microservices environment.
Ideally, your service should provide a generic, programmatic API that is flexible enough to support multiple UIs (or other non-UI applications) without having any knowledge of how the UIs work.
It sounds like you have some decisions to make about what responsibilities your service will and won't take on:
Does it make more sense for your generic orders service to facilitate the storage/retrieval/completion of incomplete orders, or to force its clients to manage this somewhere else?
Does it make more sense for your generic service to provide facilities to assist in the tracking of workflows, or to force the UIs that need that functionality to find it elsewhere?
For clients that want to show list boxes, does it make sense for your generic orders service to provide APIs that aid in populating those boxes?
Should we let each application capture the data the way it wants (and persist it if needed in its own database) and let them call our microservice only when an order is complete and compliant to our API contract?
It really depends on whether you think that's the most sensible way for your service to behave. Something that will play into that will be how similar or dissimilar the needs of each UI is. If 4 out of 5 UIs have the same needs, it could well make sense to support that generically in your service. If every single UI behaves differently to the others, putting that functionality in your generic orders service would amount to storing frontend code somewhere that it doesn't belong.
It seems like there might also be some organisational considerations to these decisions. If the teams using your service are only frontend teams (i.e. without capacity/skills to build backend services), then someone will still have to build the backend functionality they require.
Should we keep our idea of having a single "order" microservice for everyone and force each client application to capture the data the same way?
Yes to the idea of having a single order service with a generic interface for everyone. With regards to forcing client applications to capture data a certain way, your API will only dictate what they need to do to create an order. You can't (and shouldn't) force anything on them about the way they capture the data before calling your service. They can do it however they like. The questions are really around whether your service supports various models of capture or pushes that responsibility back to the frontend.
What would be your best advice to manage this issue?
Collaborate with the teams that will use the service. Gather as much information as you can about the use cases in which they intend to use it. Discover what is common for the majority and choose what of that you will support. Create a semi-formal spec (e.g. well-documented Open API), share it with the client teams, ask for feedback, and iterate. For the parts of the UIs that aren't common across clients, strongly consider telling those teams they'll need to support those elements of their design themselves, especially if they represent significant work on your end.
I have an application API that is used In two scenarios:
My frontend application uses it to interact with the server
A client is using it for development of CLI tool so there is an open documentation of the API.
At start all of the endpoints were kind of generic so they have been used in both scenarios, but as my application grows i have a need to :
create special endpoints for my frontend application for optimization, for example an endpoint to some statistics screen
Change some of the basic API results structures that are not backward compatible and can break the Clients
usage.
What is the best practice to design an API to meet these needs?
How is should be design correctly so it will be adjusted
to the frontend needs and on the other side will be robust enough to not break the Client's applications?
frontend specific endpoints along with General ones?
What is the best practice to design an API to meet these needs?
This highly depends on your scenario. Is your API going to be used internally only or will it be made publicly available to an unknown number of developers and integrators? What is the expected lifetime of the API? Will it evolve?
How is should be design correctly so it will be adjusted to the frontend needs and on the other side will be robust enough to not break the Client's applications?
I recommend to commit to API contracts and use a specification for these contracts. I prefer the OpenAPI specification as it will come with a lof of benefits. Make sure you invest a lot of time and team effort (product owner, project managers, backend & frontend devs) to develop the contract in several iterations. After each iteration test the specification by mocking the API and clients before turning over to to implement your frontend app or cli client.
frontend specific endpoints along with General ones?
I would not do that, but I do not know you context. What does a frontend specific endpoint mean? If it means that as of today the endpoint should be only used by the frontend application but is of no use for the current cli client than I think it is just a matter of perspective. Make it a general endpoint and just use it by the frontend app. If it somewhat provides sensitive information that should be access only by the frontend you need to think about authentication and authorization. I recommend implementing Oauth2 for that.
create special endpoints for my frontend application for optimization, for example an endpoint to some statistics screenfrontend specific endpoints along with General ones?
I would suggest to implement all endpoints in your API and use OAuth2 as authentication. Use the scopes of the OAuth approach to manage authorization and access to different endpoints for each client (frontend app, cli).
You wrote you need to:
Change some of the basic API results structures that are not backward compatible and can break the Clients usage.
Try to avoid making breaking changes to your API. If it is used internally only you may be in control of the different clients accessing the API but even than the risk of breaking a client is high.
If you need to change existing behaviour you should think about API versioning or API evolution, which is a controversly discussed topic with a lot of different opinions and practices.
What is the best practice to design an API to meet these needs?
Design your resource representations so that they are forward and backwards compatible by design. Fundamentally, they are messages, so treat them that way; new optional fields with reasonable defaults can be added to the messages, but the semantics of a message element should never change.
If you dig through the old XML literature, you'll find references to ideas like Must Ignore and Must Forward -- those are the sorts of princples that also apply to the representations of long lived resources.
Create new resources when the existing resources cannot be conveniently extended to cover your new use case.
I thought I knew what REST/"RESTFul", restfulservices, webservices, SOA and microservices were but I came across so many different definitions that I reached the conclusion that those terms are overused, misused , or simply badly defined.
I hope to have a clear understanding of what the aforementioned terms represent, their concrete definition , their commonality and differences, advantages vs disadvantages, and most importantly the bottom line - the most important things to remember in order to use those terms appropriately.
Disclaimer: most of this post is subjective. No attempt has been made here to strictly define anything, just trying to contextualize and give a global overview of the concepts and how they relate to each other.
I thought I knew what REST/"RESTFul", restfulservices, webservices,
SOA and microservices
I'd say that all these terms fall into the umbrella of Service Oriented Architectures (SOA). Web services is a SOA using web-related technologies. REST and its subset RESTful are a set of practices to implement web services. Finally, microservices are a new set of SOA practices.
I hope to have a clear understanding of what the aforementioned terms
represent
I'll try to address this point, but using informal definitions and without entering into advantages and disadvantages. That'd be way too long and I think the biggest points should be obvious from the explanations.
SOA
I think the name is self-explanatory in this case: SOA -- which stands for Service Oriented Architecture -- refers to architectures designed with a focus on services. Now, the tricky part here is what you may or may not consider a service and that is a whole different topic.
Web services
This accounts for the subset of SOA using web-related technologies. This typically involves HTTP and XML but it could also use FTP. I think the term web here is quite vague as it generally refers to standard Internet technologies.
REST(ful)
REST is a subset of web services -- and hence a SOA -- that revolves around using HTTP for communication. There are a certain set of common practices such as a certain given relevance to URLs.
About 10 years ago when I was introduced to REST, RESTful was presented to me as a more strict REST implementation where a resource would have a unique URI and it would be managed through CRUD operations mapped to HTTP verbs -- Create = POST, Read = GET, Update = PUT, Delete = Delete.
Updating user information through a HTTP GET or POST request o a /users/1/update URL would be perfectly valid in REST, but it would not be RESTful. For the latter, the approach would be to use an HTTP PUT or PATCH over /users/1 (which would also be the URL for the rest of the operations, simply varying the HTTP verb).
I find that this distinctions has become blurred over the years. However, it still stands that RESTful is a more strict subset of REST. (The exact requirements may be debatable.)
EDIT - A more formal definition:
REST stands for Representational State Transfer and was presented by Roy Fielding in his Ph.D. thesis as an architectural style for distributed hypermedia systems. The emphasis goes into the hypermedia and self-containment decoupling the client from most beforehand knowledge among others. A website is an example: it consists on a single URI (the website root) and a media type (HTML) through which the server offers all the information a client needs regarding resources and all possible interactions.
I'd say 99% people talking about REST really mean RPC or HTTP-based interfaces: using HTTP endpoints to invoke certain actions or query data. Fielding himself has tried to clarify this. Any API formed by a set of predefined URLs expecting certain HTTP verbs and some parameters falls into that 99%. So does my description above. However, I doubt the term itself can ever survive its misuse and I think we must accept its new meaning.
Microservices
This is the more recent term; it promotes implementing applications as a set of simple independently deployable services. This contrasts with the classic approach of SOA architectures as a set of quite complex services used to build complex systems, tipically involving an enterprise service bus. However, it is important to note that although typically SOA gets associated with such systems, it is a broader term and indeed, microservices are also a subset of SOA.
Microservices usually appear hand-by-hand with modern JavaScript full-stacks -- i.e. using JavaScript for all the vertical components, from the server up to user interface. Arguably this is so because using these JavaScripts full-stacks may speed up development thanks to the simplified integration. These stacks, and hence microservices implemented using them, are usually architected through REST but from a theoretical point of view, there is nothing preventing you from using a different approach to the same philosophy.
Let me introduce you a taxonomic view of those term:
Microservices
are a subtype of services specialized by minimal responsibility.
Webservices
are a subtype of services as well, specialized by the type of service they provide wich fall under web requirements and needs.
SOA
is a subtype of architectures and hence a structural view of some components and their relationships, where happens to be services and communications between those services respectively.
rest
is a subtype of communication, underlying http protocol.
restful
is a subtype of architectures (a structural view of some components and their relationships) where specialized by relationships among components restricted to be rest communications.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
I was under the assumption that REST was a web service but it seems that I am incorrect in thinking this - so, what is REST?
I've read through Wikipedia but still cant quite wrap my head around it. Why to do many places refer to API's as REST API's?
REST is not a specific web service but a design concept (architecture) for managing state information. The seminal paper on this was Roy Thomas Fielding's dissertation (2000), "Architectural Styles and the Design of Network-based Software Architectures" (available online from the University of California, Irvine).
First read Ryan Tomayko's post How I explained REST to my wife; it's a great starting point. Then read Fielding's actual dissertation. It's not that advanced, nor is it long (six chapters, 180 pages)! (I know you kids in school like it short).
EDIT: I feel it's pointless to try to explain REST. It has so many concepts like scalability, visibility (stateless) etc. that the reader needs to grasp, and the best source for understanding those are the actual dissertation. It's much more than POST/GET etc.
REST is a software design pattern typically used for web applications. In layman's terms this means that it is a commonly used idea used in many different projects. It stands for REpresentational State Transfer. The basic idea of REST is treating objects on the server-side (as in rows in a database table) as resources than can be created or destroyed.
The most basic way of thinking about REST is as a way of formatting the URLs of your web applications. For example, if your resource was called "posts", then:
/posts Would be how a user would access ALL the posts, for displaying.
/posts/:id Would be how a user would access and view an individual post, retrieved based on their unique id.
/posts/new Would be how you would display a form for creating a new post.
Sending a POST request to /users would be how you would actually create a new post on the database level.
Sending a PUT request to /users/:id would be how you would update the attributes of a given post, again identified by a unique id.
Sending a DELETE request to /users/:id would be how you would delete a given post, again identified by a unique id.
As I understand it, the REST pattern was mainly popularized (for web apps) by the Ruby on Rails framework, which puts a big emphasis on RESTful routes. I could be wrong about that though.
I may not be the most qualified to talk about it, but this is how I've learned it (specifically for Rails development).
When someone refers to a "REST api," generally what they mean is an api that uses RESTful urls for retrieving data.
REST is an architectural style and a design for network-based software architectures.
REST concepts are referred to as resources. A representation of a resource must be stateless. It is represented via some media type. Some examples of media types include XML, JSON, and RDF. Resources are manipulated by components. Components request and manipulate resources via a standard uniform interface. In the case of HTTP, this interface consists of standard HTTP ops e.g. GET, PUT, POST, DELETE.
REST is typically used over HTTP, primarily due to the simplicity of HTTP and its very natural mapping to RESTful principles. REST however is not tied to any specific protocol.
Fundamental REST Principles
Client-Server Communication
Client-server architectures have a very distinct separation of concerns. All applications built in the RESTful style must also be client-server in principle.
Stateless
Each client request to the server requires that its state be fully represented. The server must be able to completely understand the client request without using any server context or server session state. It follows that all state must be kept on the client. We will discuss stateless representation in more detail later.
Cacheable
Cache constraints may be used, thus enabling response data to to be marked as cacheable or not-cachable. Any data marked as cacheable may be reused as the response to the same subsequent request.
Uniform Interface
All components must interact through a single uniform interface. Because all component interaction occurs via this interface, interaction with different services is very simple. The interface is the same! This also means that implementation changes can be made in isolation. Such changes, will not affect fundamental component interaction because the uniform interface is always unchanged. One disadvantage is that you are stuck with the interface. If an optimization could be provided to a specific service by changing the interface, you are out of luck as REST prohibits this. On the bright side, however, REST is optimized for the web, hence incredible popularity of REST over HTTP!
The above concepts represent defining characteristics of REST and differentiate the REST architecture from other architectures like web services. It is useful to note that a REST service is a web service, but a web service is not necessarily a REST service.
See this blog post on REST Design Principals for more details on REST and the above principles.
It stands for Representational State Transfer and it can mean a lot of things, but usually when you are talking about APIs and applications, you are talking about REST as a way to do web services or get programs to talk over the web.
REST is basically a way of communicating between systems and does much of what SOAP RPC was designed to do, but while SOAP generally makes a connection, authenticates and then does stuff over that connection, REST works pretty much the same way that that the web works. You have a URL and when you request that URL you get something back. This is where things start getting confusing because people describe the web as a the largest REST application and while this is technically correct it doesn't really help explain what it is.
In a nutshell, REST allows you to get two applications talking over the Internet using tools that are similar to what a web browser uses. This is much simpler than SOAP and a lot of what REST does is says, "Hey, things don't have to be so complex."
Worth reading:
How I Explained REST to My Wife (now available here)
Architectural Styles and the Design of Network-based Software Architectures
http://en.wikipedia.org/wiki/Representational_State_Transfer
The basic idea is that instead of having an ongoing connection to the server, you make a request, get some data, show that to a user, but maybe not all of it, and then when the user does something which calls for more data, or to pass some up to the server, the client initiates a change to a new state.