In the API I'm putting together, I perform an Action over a set of entities. The issue I'm having is how to allow the action to vary depending on the client's preferences and supported methods.
Some of the action types will need the client to provide additional options: for instance, one of the actions will result in an email being sent, so the client needs to provide the body, recipients and so on. The server may know about more action types than the client does. For instance, a new sending method could be added, but an old client isn't going to know how to set up the options for it. As well as that, there are action types that require no options from the client, and hence all clients can use that as soon as the server is enabled for it.
As well as varying the action types based on those supported by the client/server, the entities selected also have an effect -- some entities are not valid for some action types.
At the end of this negotiation, the client (ultimately the end user) is free to choose from any of the 'no-option' action types applicable to these entities, or any of the 'need-options' action types applicable to these entities, and supported by both the client and the server.
Actions are triggered by setting a status field to committed or similar.
My thoughts so far are to provide a generic DoAction resource, with a sub-collection of the entities. A property on this resource lets you specify the 'ActionType'. There is then another sub-resource called ActionOptions and it's this where you either set the options for the particular type you're using, or leave it empty for 'no-option' types.
The issue I'm having is to decide if this is the best approach, or if something involving content types would be better, and also how to negotiate the list of available action types for the client, including the no-option types which the client can support even if it doesn't explicitly know about it.
I decided to add two read-only collections to the DoAction resource, one listing the no-option action types, and one listing the need-options types (plus could optionally include schema-like info there). These collections are based on the entities included.
The client sets their action type and the options, which is a dynamic key/value store. When the status is changed to committed, that's an opportunity to validate the resource prior to performing the action.
Related
I have a resource, as an example a 'book'.
I want to create a REST POST endpoint to allow consumers to create a new book.
However, some of the properties are required and computed by API, and others were actually taken as they are
Book
{
name,
color,
author # computed
}
Let's say the author is somehow calculated in API based on the book name.
I can think of these solutions each has its drawbacks:
enforce consumer to provide the author and just filter it (do not take into account as an input) # bad because it is very unpredictable why the author was changed
allow the user to provide author # same problem
do not allow the user to provide an author and show an exception if the user provides it
The last solution seems to be the most obvious one. The main problem I can see is that it is inconsistent and can be bizarre for consumers to see the author later on GET request.
I want my POST endpoint to be as expressive as possible. So the POST and GET data transfer objects will look almost the same.
Are there any simple, expressive, and predictable patterns to consider?
Personally I'm a big fan of using the same format for a GET request as well as a PUT.
This makes it possible for a client to do a GET request, add a property to the object they received and immediately PUT again. If your API and clients follow this pattern, it also means it can easily add new properties to GET requests and not break clients.
However, while this is a nice pattern I don't really think that same expectation exists at much for 'creation'. There's usually many things that make less less to require as a property when creating new items (think 'id' for example), so I usually:
Define a schema for PUT and GET.
Define a separate schema for POST that only contains the relevant properties for creation.
If users supply properties not in the schema, always error with a 422.
some of the properties are required and computed by API
Computed properties are neither required nor optional, by definition. No reason to ask consumers to pass such properties.
do not allow the user to provide an author and show an exception if the user provides it
Indeed, DTO should not contain author-property. Consumers can send over network whatever they want, however it is the responsibility of the API-provider to publish contract (DTO) for consumers to use properly. API-provider controls over what properties to consider, and no exception should be thrown, as the number of "bad" properties that can be sent by consumers is endless.
So the POST and GET data transfer objects will look almost the same
Making DTOs of the same resource look the same is not a goal. In many cases, get-operation exposes a lot more properties than post-operation for the same resource, especially when designing domain-driven APIs.
Are there any simple, expressive, and predictable patterns to consider?
If you want your API to express the fact that author is computed, you can have the following endpoints:
POST http://.../author-computed-books
GET http://.../books/1
Personally, I wouldn't implement that way since it does not look natural, however you can get the idea.
I want my POST endpoint to be as expressive as possible. So the POST
and GET data transfer objects will look almost the same.
Maybe just document it instead of relying explicit stuff like it must be almost the same as the GET endpoint.
E.g. my POST endpoint is POST /number "1011" and my GET endpoint is GET /number -> 11. If I don't document that I expect binary and I serve decimal, then nobody will know and they would guess for example decimal for both. Beyond documentation another way of doing this and to be more explicit is changing the response for GET to include the base {"base":10, value:"11"} or changing the GET endpoint GET /number/decimal -> 11.
As of the computed author I don't understand how you would compute it. I mean either a book is registered and the consumer shouldn't register it again or you don't know much about the author of it. If the latter, then you can guess e.g. based on google results for the title, but it will be a guess, not necessarily true. The same with consumer data, but at least that is what the consumers provided. There is no certainty. So for me it would be a complex property not just a primitive one if the source of the information matters. Something like "author": {name: "John Wayne", "source": "consumer/service"} normally it is complex too, because authors tend to have ids, names, other books, etc.
Another thought that if it is weird for the consumers instead of expected, then I have no idea why it is a feature at all. If author guessing is a service, then a possible solution is making the property mandatory and adding a guessing service GET /author?by-book-name={book-name}, so they can use the service if they want to. Or the same with a completely optional property. This way you give back the control to the consumers on whether they want to use this service or not.
Background
We have very strict auditing requirements and want to be able to correlate every action our system takes on behalf of the user to a specific authentication operation (sign-on). In addition to these strict auditing requirements, we also have some complex authorization requirements unsolvable by simple claims based authorization.
Considering both of these together led me to wondering the feasibility of using an 'envelope' type design, where messages sent stemming from a user request are wrapped in an envelope containing the necessary information, such as their auth token and info about the sending machine. Now, it would be fairly simple enough to add a property for this token to every message, but that seems tacky and since its a rather cross-cutting concern, I would rather it not pollute every protocol in the system, which is why I'm thinking the envelope idea is worth considering. This approach would also require the cooperation of every actor in the system and my goal is to have this be transparent to actors who don't need any of this information, but also make the information available in case actors do need it. In the case of actors needing it, it's also OK if they just accept the envelope type directly.
Imagined Solution
Overview
Wrap each Tell operation in an envelope used to transport required contextual information
Perhaps implemented w/ a custom actor ref provider and actor ref wrapping the ones configured
Unwrap envelope, if exists, on each receive operation
Custom mailbox
Would also handle sending a message to the auditing service
How to make the contextual information available to the actor?
Can we add to the actor's Context object somehow?
Also acceptable for actor to accept the envelope type/not use custom mailbox in this case
Discussion
In order to make this all transparent, my initial thinking is to 'intercept' the send/receive operations. I understand enough akka.net to implement a custom mailbox and I think this would be the way to go for this kind of approach, but I'm open to other ideas. The mailbox would perform the unwrap and make the contextual information available to the actor in case it's required (99% of the time it's not, likely better to just accept the envelope directly when it is required to be explicit). The mailbox would also handle fulfilling the auditing requirement by sending a message to the auditing service w/ the required information, which not only includes the contextual information from the request, but also local machine information to know where/who did the processing.
The part I'm second guessing myself on is intercepting the send operation (Tell). Since IActorRef instances are created via a configured IActorRefProvider and since this guy handles the Tell operation (via it's created IActorRef instances), I think it makes sense to write a custom IActorRefProvider and a custom IActorRef. Both would wrap the implementations that are configured (decorator pattern), and the custom IActorRef would provide the required behavior in it's Tell method. For webapi apps (only entry point for users), it would pull the required contextual information from HttpContext (one custom ref provider) and for backend apps (another custom ref provider), it would pull the required contextual information from the current message's context. I'm not sure how to add data to the actor's Context property, but I'm assuming it is possible.
With these two pieces in place, the contextual information would effectively be passed along, from actor to actor, and service to service. So even if a message is 20 actors down the line, if it was initially instigated by a user via the REST API, it would still have that contextual information, thereby allowing a full and complete audit and tracing of each action our system takes back to a specific sign on.
What I'm Hoping For
The primary thing I'm hoping for with this post is validation that this is a reasonable approach to take, and if not, why not and alternate suggestions for achieving the desired behavior. Also very welcomed would be any code samples for custom mailboxes/actor ref/actor ref providers and extra cookies if they're doing something similar to what I'm trying to accomplish here. Another welcomed tidbit is how to do the mailbox configuration so I don't need to manually update all of my Props with the custom mailbox implementation. Akka.net configuration is definitely a weaker point of mine, particularly the deployments section, so any core knowledge/articles/advice here is greatly appreciated!
Thanks for taking the time to read this! Any and all help is much appreciated!
Other StackOverflow Issues:
The answers provided in these issues require the cooperation of every actor. Ideally this is all transparent and actors that don't need to use this contextual information can be written as if it didn't exist.
Passing Contextual Information
How to elegantly log contextual information along with every message
There were a couple others I viewed [can't find them right now for some reason], but they all either required cooperation or global shared state [isn't that what akka avoids? :p]
Phobos, a proprietary observability library for Akka.NET, wraps all messages inside a distributed tracing context - which can be aggregated back together again in an off-the-shelf tracing system that supports OpenTracing, such as Jaeger / Zipkin / Azure Application Insights.
You can append custom data to each of the traces that are captured inside your actors via the Context.GetInstrumentation() method inside any of your actors' - custom data can include tags that might include a unique userId, a transaction Id, and so on. That's all part of the OpenTracing specification.
Disclosure: I work for Petabridge, the makers of Phobos. It's proprietary and costs money to use, but it's purpose built to offer this type of decentralized, but complete tracing out of the box.
Alternatively, if you didn't want to use Phobos you might be able to accomplish this using a custom messaging protocol for context propagation and structured logging with the Akka.Logger.Serilog library.
I'm designing a restful web service and I was wondering what should I name my DTOs. Can I use suffixes like Request and Response for them? for example for addUser service, there will be 2 DTOs named: AddUserRequest and AddUserResponse.
Does your organization already have a schema that describes a canonical user that you pass in? If that's what you're using, of course you would use the name from that schema. Otherwise, describe them just as you would any class or schema element.
Note that since a DTO doesn't contain its own methods, you probably would not give it a name with an action verb.
However, consider calling them AddUserRequest and AddUserResponse, especially if the method requires more info than just your regular user DTO. This fits with the Interface Segregation Principle in that your interface parameters should be specifically tailored to the request itself (it shouldn't require elements that are unrelated to the request; and you shouldn't have function-type parameters that change the request, those should be extracted into their own calls.) The AddUserRequest might then contain an element called User that holds the user-specific data, and another element holding the set of other associated data on the request, perhaps groups or access permissions, that sort of thing.
DTOs (Data Transfer Object) are like POJOs(Plain Old Java Objects). It should only have getters and setters and not any business logic.
From Wikepedia:
A data transfer object is an object that carries data between
processes. The motivation for its use is that communication between
processes is usually done resorting to remote interfaces (e.g., web
services), where each call is an expensive operation. Because the
majority of the cost of each call is related to the round-trip time
between the client and the server, one way of reducing the number of
calls is to use an object (the DTO) that aggregates the data that
would have been transferred by the several calls, but that is served
by one call only.
The difference between data transfer objects and business objects or
data access objects is that a DTO does not have any behavior except
for storage and retrieval of its own data (mutators and accessors).
DTOs are simple objects that should not contain any business logic
that would require testing.
This pattern is often incorrectly used outside of remote interfaces.
This has triggered a response from its author[3] where he reiterates
that the whole purpose of DTOs is to shift data in expensive remote
calls.
So ideally for those actions you should create some helpers or you can add those as controllers.
Since it is a RESTful service, ideally the user addition/creation request should send back 201 created HTTP status code , with userId in location header and no response body. For the request, you could name it like UserDetails or UserData or simply User. Refer https://pontus.ullgren.com/view/Return_Location_header_after_resource_creation
This is a generic design question, but where should the responsibility fall in this situation? Should it be the caller's responsibility to check if a record already exists and then call Update? Or should it be the responsibility of the API to make that decision?
In the first scenario, the problem is that the caller is burdened with the business logic, but in the second scenario, the logic pollutes the API and creates hybrid behavior, violating the separation of concerns principle.
Implementing a CreateOrUpdate endpoint will be breaking some REST principles, but may be convenient for the application developer. You are thinking in terms for a remote function call rather than in terms of resource-oriented API.
Consider this: the API URL identifies the resource.
If the URL points to a collection (i.e. /customers/) then the Create action (typically mapped to the POST method) certainly makes sense. The Update function might makes sense, if you want allow update to multiple resources at one. The POST should return code 201 and an identifier to a newly created resource (i.e. /customers/1); or if the create failed due to resource already existing it should return code 409; 400 if some other constraints like data validation are not met.
If the URL points to an existing resource (i.e. /customers/id/1) then Create action does not make sense and should result in code 400. The update is typically mapped to the PUT method (or sometiemes PATCH, if partial resource update) and generally would return 200 if the update was successful or 4xx series if not.
If you choose to create a /CreateOrUpdate endpoint, which takes POST requests you will have to design your own protocol around it because its behavior and return values will be different depending on circumstance.
#Evert the PUT can be used for create but only when you require client to formulate the endpoint URI with the identifier i.e.
PUT /users/myusername
Problems with that are:
the client must discover an available one,
if a natural identifier is used, there may also exist a natural reason for changing it, which depending on the implementation may be problematic
The main point I am making is to avoid creating REST API endpoints, which represent an action (function). Instead use HTTP methods to effect respective actions on persisted resources.
In my application, when a user is created, an Event called UserCreatedEvent is thrown.
This user must have all his description data retrieved from Facebook (with his authorization of course) and should be treated by some custom process.
I chose to apply eventual consistency (using Akka and his eventStream feature to handle events) between the fact of saving the user aggregate and the fact to retrieve all his description data and apply them, since it involves some call network to Facebook.
The point is I also allowed any newly created user to override some of the description (job, age etc.) through the REST api PUT /api/users/:id.
1) Should the process of handling UserCreatedEvent (basically an Akka actor) call this api (causing an indirection) to assign default user description (from Facebook) or should it retrieve and update user itself?
2) Should the process of handling UserCreatedEvent and the api aiming to manage User (CRUD) be part of the same bounded context? (in that case, no recommendation to involve the indirection).
I'm not sure I would call this eventual consistency, since consistency (making sure that an entity respects invariants) is not at stake. This is more like out-of-band asynchronous data completion.
What hoops this side process has to go through again basically depends on your context :
REST API if there's important stuff there you want to reapply (logging, security, whatever)
Application Service / Command handler layer if you want that data completion to be treated as a full blown modification with proper validation (e.g. did Facebook return data that would be unsupported in your application ?)
In the domain layer, you could model it either as just any other modification of the User, or as a specific, maybe more intention-revealing operation : User.completeDescriptionData(...)
I wouldn't necessarily place this in a different Bounded Context since it doesn't introduce a new definition of User. It's important that the part that knows the nitty gritty details of talking to Facebook is in a separate non domain layer though.