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?

CodePudding user response：

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.

CodePudding user response：

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:

1. Define a schema for PUT and GET.
2. Define a separate schema for POST that only contains the relevant properties for creation.
3. If users supply properties not in the schema, always error with a 422.