Implement save of New School on server

[Brian Lewis]

Devise a standard for REST API to distinguish between Update and Create. Support data items in which the primary ID may be user-defined or system-defined (ie no key is supplied on a create request).

Implement these standards on School Save

[Brian Lewis]

Working through this, I would like to standardise on these Http methods and status codes for Create, Read, Update Delete operations on a single record:

Read

GET api/<entity>/<id>

Create:

POST api/<entity>/<new id>

OR if the id is created on the server ( either by a Identity field or a process to generate a key; e.g. schNo)

api/<entity>

If a primary key is supplied, and is a duplicate will return 422 Unprocessable Entity

Update:

PUT api/<entity>/<primary key>

Primary key is required in this case

If the key does not exist, returns 410 Gone

Concurrency conflicts will return 409 Conflict, together with the current versions of all passed in fields (including pRowversion). The new row version can be submitted with the client's data to force an update.

Delete:

DELETE api/<entity>/id

Ideally, I'd like to pass the row version in with the delete as well - you should be prevented deleting a record that someone has edited since you read it??

But, as this discussion points out it may not be possible to pass a body with a DELETE.

To be clarified at this stage.

In General:

Formats for read (get) create(post) and update (put) match the outputs of the get() post() and put() methods added to entities by restangular. This is A Good Thing.

Successful actions will return 200 Probably should ensure that we don't get 204 No Content which may mean that an operation has completed successfully on the server, but seems to upset restangular.

Errors occurring in the Sql Server will return 400 Bad Request.

Errors occurring in processing will return 500 Internal Server Error.

Some procedures and triggers in the database respond to certain errors by returning an error message that is a small piece of xml in the form

<ValidationError field="<fieldname>"> message</ValidationError>

These will return 400 , but will be recognised by client side processing - ie this gives the option to set focus to the offending field. This is inplemented in RowHeaderManager.

RowHeaderManager component and ApiUi service on the client will provide some standardised Ui in response to these messages.

[Ghislain Hachey]

Sounds good. I typically follow follow RESTful principals as in the book RESTful Web Services. The POST/PUT for creating is discussed here. The two highest rated replies are inline with the book I refer to. Your approach is a little different. While this is not something I'll argue beyond this I thought I'd share my 2 cents.

[Brian Lewis]

Sample posts and responses:

Attempt to add a new with a duplicate key:

[Brian Lewis]

Update: concurrency error - returns the same set of fields that were supplied, including new value of pRowversion

[Brian Lewis]

The POST/PUT for creating is discussed here.

I did read this, and I don't think the above strays too far.

Probably main point of contention is:

Do you name your URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.

However suppose a user adds a new school and supplies a schNo that is already in use.

PUT api/schools/<school no> would then potentially overwrite the existing record when this really should be an error.

Furthermore, both the post() and put() functions generated by restangular will append this primary key to the Url - so we can't send a post to

api/schools

and have schNo specified in the body without it also appearing on the Url.

So to me I think this simple interpretation of post and put is easy to understand, works with restangular, and is easy to handle in Web Api where the routing is dependant on the HTTP method, like so:

[Brian Lewis]

Change to the above: just use 404 Not found, rather Gone when a record to update is Not Found.

[Brian Lewis]

Branch Issue87 merged.