Proposal: Simpler URLs

[JerryNixon]

REST Paths

The current approach for a REST URL is like this:

• get http://localhost:5000/api/book
• post http://localhost:5000/api/book
• put http://localhost:5000/api/book/id1/123/id2/234
• patch http://localhost:5000/api/book/id1/123/id2/234
• delete http://localhost:5000/api/book/id1/123/id2/234

Notice how the put, patch, and delete URLs include the keys in the url.

In addition they require those properties NOT to be in the payload.

The Model

In the get operation, this typical model will be returned to the consumer.

Note that the key fields are in the model payload.

These must be removed before any write operation is called.

The Config

Let me bring our attention to the config settings:

That's right, we already know which properties are key properties.

These are optional, but so is this behavior change.

Behavior change

1. Keep supporting the keys-in-the-url approach
2. Also support a simple url http://localhost:5000/api/book if these conditions are met:
   a. The config file includes key fields in the entity setup.
   b. The inbound payload includes the key properties.
   c. Only for operations: put, patch, and delete
3. Use the key values from the payload instead of the url.
4. No longer throw an error when key fields are include in the inbound payload 👀

Then end. This makes things so much simpler for consumers by about 100.

PS: this is only for REST of course.

[seantleonard]

post already requires the primary keys to be in the request body and would result in an HTTP 400 bad request error such as:

• POST - https://localhost:5001/api/Journal/id/2021

{
    "error": {
        "code": "BadRequest",
        "message": "Primary key for POST requests can't be specified in the request URL. Use request body instead.",
        "status": 400
    }
}

Can look into for PUT and PATCH, though there is an interesting SO discussion regards to DELETE and HTTP specification comments: https://stackoverflow.com/a/299696 (e.g. 'content received in a DELETE request has no generally defined semantics') https://www.rfc-editor.org/rfc/rfc9110.html#name-delete

[JerryNixon]

I hear what you are saying:

1. post is unaffected here
2. delete uses the URL by convention

If we limit this discussion to put and patch we might get further faster.

The design goals remain the same:

1. And most importantly, don't require the consumer to modify the model structure (remove keys).
2. Reduce the complexity of the url if we can.

The reasons remain the same:

1. In a system with hundreds of models, this starts to matter more.
2. Modifying models in .NET (especially) is complex.

The behavior changes remain:

1. Don't throw when keys are included in put and patch ops
2. Use keys if they exist in the model and are defined in the config.

Everything except delete becomes a simpler ordeal.

Does this break anything?

[Aniruddh25]

@JerryNixon,
Today, we only support mutations on a single item, but find i.e. get is supported for multiple items as well. We reserved the url format for single item to be of the format: http://localhost:5000/api/book/id1/123/id2/234, and for many operations to be http://localhost:5000/api/book.

So, in future, put on http://localhost:5000/api/book will be used for bulk updates. For those kinds of put, the required request body would be expected as an array. We could achieve what you are proposing by providing a single value in the array yet targeting the endpoint for a Many operation.

For post, even the single item operation requires a request body, that single item we provide in an array.

That said, we do have an open issue to simplify the url for single item get, put, patch, delete operations to avoid mention of the key-field: #1085

Hope this makes sense.
Thanks!