I'm designing a REST API (implemented with ASP.NET Web API, not ASP.NET core, because we can't upgrade it right now).
I'm looking for the best solution to partially update an entity.
For example, the "Person" entity has 100 properties, and a third party system only has to update the "PersonValidityDate".
What is the best and simplest solution to do it ?
I read some article about the PATCH verb, with JSON patch or JSON merge patch, but it seems a bit complicated and not supported by everyone... Is it ?
I'm looking for a very simple solution to do it, that any integrator can understand and use...
What do you suggest ? Is PATCH often used?
If I use POST/PUT and only give the properties to update and ignore the other properties, when the body is deserialized, nullable properties will be null. How can I distinguish the properties set to NULL explicitely and not provided properties ?
According to RFC 5789
Several applications extending the Hypertext
Transfer Protocol (HTTP) require a feature to do partial resource
modification. The existing HTTP PUT method only allows a complete
replacement of a document. This proposal adds a new HTTP method,
PATCH, to modify an existing HTTP resource.
So you should use a PATCH request for partial update of the object and PUT for complete object replacement.
And you should not use the complete model in patch request with empty/null fields instead use the new model for PATCH request.
You can check more example here
Related
I'm currently trying to figure out which options does retrofit offer to add an interceptor only to specific calls.
Background & use cases
I'm currently using retrofit 1.9
The use case is pretty simple. Imagine a user who needs to login and get a session token. There is a call.
/**
* Call the backend and request a session token
*/
#POST("auht_endpoint")
Observable<Session> login(...);
All other calls will require a token from the above session in the form of a request header. In other words, all subsequent calls will have a header which provides the session token to the backend.
My question
Is there a simple way of adding this header only to specific calls through interceptors?
What I've tried so far
Obviously the easiest approach was to add the #Header annotation to the specific calls and providing the token as a parameter
I guess one can inspect the url in the request inside the interceptor. Not very flexible.
Create different rest adapters with different interceptors. I heard you should avoid creating several instances of the rest adapter for performance reasons.
Additional info
I'm not committed to interceptors, I would use other solutions
I've said I'm using retrofit 1.9, but I'd be also interested in a way to do it with retrofit 2.x
Please note this is not an answer, comment box was too small.
I've recently had this problem and I came up to the same possible solutions as you.
First of all I put aside double adapters - thats a last resort.
#Header field seems ok, bacause you explicitly define that this specific request needs authorization. However it's kinda boring to use.
Url inspection in interceptor looks "ugly", but I've decided to go with that. I mean if all requests from a one specific endpoint need that authorization header then what's the problem?
I had two other ideas:
Somehow dynamically replace/modify okHttpClient which is used with Retrofit. After some tests I figured that it's not possible.
Maybe create some custom annotation #AddAuthorizationHeader to the call definition, which will do everything for you, but I guess it wouldn't be possible either.
And in this matter Retrofit 2.x doesn't bring anything new.
Currently I'm working on a CMS containing on a RESTful webservice. For the regular REST actions, I use the default HTTP methods GET, PUT, POST and DELETE. However, I'm thinking of adding a custom method MAINTENANCE, which I can use for maintenance purposes, like integrity checks, re-indexing, etc. These kind of maintenance can only be invoked by administrators of the CMS.
My webservice supports overriding the HTTP method by defining the url parameter _method. This way I can 'post' a form, setting the _method to PUT. I can also use this same parameter to set the method to MAINTENANCE. Technically it is fairly easy to implement a custom HTTP method.
My questions is more ethical about proper design. On one hand, custom HTTP methods are allowed and technically not difficult to implement. On the other hand, some people advice not to use custom HTTP methods.
Should I use custom HTTP methods for maintenance tasks? Or are there other best practices?
Integrity checks and re-indexing are not resource actions that you want to expose to a user. These can be achieved via a different servlet that's non_REST.
Adding more methods to HTTP is not a normal practice. You can look some to the REST interfaces that are public.
I am already using the standard WebAPI and returning JSON objects to my client. Now I saw an application that returned OData.
Can someone explain if there is any reason for me to use OData if I do not want to query my data from anything other than my own client running in the browser. Are there advantages that I could get through using OData ?
If you are only using your data in your own browser application, there is only few advantages to use OData in your situation:
OData is able to provide metadata about your service interface that can be used to generate client code to access the service. So if you have lots of client classes that you need to create, this could speed up your process. On the other hand, if you can share your classes between the server and an ASP.NET based client or if you only have a few classes, this might not be relevant in your situation.
Another - bigger - advantage in your situation is the support for generic queries against the service data. OData supports IQueryable so that you can decide on the client side on how to filter the data that the service provides. So you do not have to implement various actions or use query parameters to provide filtered data. This also means that if you need a new filter for your client, it is very likely that you do not have to change the server and can just put up the query on the client side. Possible filters include $filter expressions to filter the data, but also operations like $skip and $top that are useful when paging data. For details on OData and queries, see this link.
For a complete overview about OData and Web API see this link.
Here are few advantages of OData.
OData is a open protocol started by Microsoft is based on Rest Services so we can get data base on URL.
It suppport various protocol like http,atom,pub and also support JSON format.
No need to create proxy classes which we used to do it in web service.
You will able to write your own custom methods.
It is very light weight so the interaction between client and server will be fast compared to web service and other technologies.
Very simple to use.
Here are few reference links.
http://sandippatilprogrammer.wordpress.com/2013/12/03/what-is-odata-advantages-and-disadvantages/
http://geekswithblogs.net/venknar/archive/2010/07/08/introduction-odata.aspx
http://www.zdnet.com/blog/microsoft/why-microsofts-open-data-protocol-matters/12700
I agree with the answers already posted, but as an additional insight...
You mentioned that:
... if I do not want to query my data from anything other than my own
client running in the browser...
You may not wish to run it normally through anything but your own cilent, but using oData you could use other querying tools for debugging. For example LinqPad allows you to use oData endpoints (such as that provided by stackoverflow).
It's probably not a good enough reason to implement oData if you don't have another reason to do so, but it's an added bonus.
I am new to ASP.NET Web API and I found that it has one limitation which is very annoying. It only supports one parameter to post method. (Read more here: Using jQuery to POST [FromBody] parameters to Web API)
From that link, it seems like they design it this way. It doesn't make any sense to me to have such strange limitation.
If anyone knows why it was designed this way, please let me know.
This is the way HTTP works. An HTTP POST sends a body. And as a web api, that body represents the resource object that is being POSTed.
That 'object' which is in the POST can be a complex object with many properties so you can create a wrapper object to represent the resource. It can also be an array of objects as a collection of resources.
As a side note, if you're designing a RESTful web api, then it's desirable to POST an single resource or array of resources (objects) to an endpoint that represents a collection of resources. For example, I post a student to /api/students and it adds that student.
You can have many parameters but you can only have one [FromBody], and that's because an HTTP message can only have one body. You can map as many parameters as you like to parameters on the query string.
I am very confused. I have a xsd file, no wsdl and apparently i send this data through SOAP. Now looking at all i went back and notice this
(using ssl) The regular session begins
with a HTTP POST request sent by the
client. The body of the request
contains XML document compliant with
SOME_API Request schema
So... i am not using SOAP at all? Am i suppose to do something with the schema file they provide me? No one here (at work) seems to know.
You should start by reading Http made really easy. Soap uses http to send its messages from client to server, and when the document you are talking about is asking you to send a message to the soap server using the HTTP protocol. A bit of googling should find you some nice soap getting started guides.
The message you send is an XML document that uses this schema. The schema defines the types of XML that are valid. Get a good XML editor such as oxygen and tell it you are making a new xml document using a schema (point to your xsd file) and see what you are allowed to type.
My search turned up these two:
Tutorial point SOAP Tutorial
W3Cschools
Just send an HTTP POST with XML that complies to the schema. You can either read the schema manually (which can be hard), or use an XML editor like Tom is suggesting, but there's another possibility: Many platforms offer tools that automatically generate classes from XSD schema, which you can later automatically serialize to get the correct XML.
For example, if you use .NET: Use the xsd.exe tool to generate classes from schema, then just fill these with information as regular classes, then use the XmlSerializer to convert the root class to XML.
Based on your description, it seems that it's not really a SOAP API at all, but rather something like XML-RPC.
Just send an HTTP POST with XML that complies to the schema. You can either read the schema manually (which can be hard), or use an XML editor like Tom is suggesting, but there's another possibility: Many platforms offer tools that automatically generate classes from XSD schema, which you can later automatically serialize to get the correct XML.
For example, if you use .NET: Use the xsd.exe tool to generate classes from schema, then just fill these with information as regular classes, then use the XmlSerializer to convert the root class to XML.
You are learning why standards should be followed.
If this is really a SOAP-based web service, then there must be a WSDL. There is no exception to that. The WSDL is meant to describe everything you need to know about the web service. I strongly suggest you ask the developers of the web service whether it is a SOAP web service, and ask them to supply a WSDL or to explain why they think they should not do that.