[REST Service] Return full entity or just the needed values - Best practice?
-
I am not sure this is the correct forum, so please excuse me if I am posting in the wrong forum. I am trying to understand the best practices in building SOA applications. Unfortunately some of are not so black or white and need experience to figure out the right approach. Here are some of them: 1) Let's say I am building a REST service for extracting data from various tables. Is it considered best practice to return the whole entity or just the necessary values? The target might be multiple platforms (web, windows and mobile apps). 2) Also, is it RESTful to join entities from multiple tables and return it as a single entity? 3) When joining entity types, should only the necessary values be returned or is it better to form a compound type composed of the basic types? Example: Consider a REST service that return's an employee's address. The address is composed of the types Apartment, Street, City and Zip Code. Each type has properties (eg: Street has starting and ending lat-lon). In the client only the address <apt number> <street name> <city code> <zip code> is required. How should the return type of a REEST service call be structured? (It would also help if anyone can provide the recommended URL syntax for this as well. Should there be a specific call like "GetEmployeeAddress" or something like ' <service URL>/Employee/<emp ID>/Address' ?) I would be very grateful for suggestions for reading materials in this topic. Thanks in advance. :)
-
I am not sure this is the correct forum, so please excuse me if I am posting in the wrong forum. I am trying to understand the best practices in building SOA applications. Unfortunately some of are not so black or white and need experience to figure out the right approach. Here are some of them: 1) Let's say I am building a REST service for extracting data from various tables. Is it considered best practice to return the whole entity or just the necessary values? The target might be multiple platforms (web, windows and mobile apps). 2) Also, is it RESTful to join entities from multiple tables and return it as a single entity? 3) When joining entity types, should only the necessary values be returned or is it better to form a compound type composed of the basic types? Example: Consider a REST service that return's an employee's address. The address is composed of the types Apartment, Street, City and Zip Code. Each type has properties (eg: Street has starting and ending lat-lon). In the client only the address <apt number> <street name> <city code> <zip code> is required. How should the return type of a REEST service call be structured? (It would also help if anyone can provide the recommended URL syntax for this as well. Should there be a specific call like "GetEmployeeAddress" or something like ' <service URL>/Employee/<emp ID>/Address' ?) I would be very grateful for suggestions for reading materials in this topic. Thanks in advance. :)
I think you're misinterpreting the meaning of a REST service. The primary key is that the server itself should be stateless; each transaction must be atomic, having nothing to do with the ones before it, and no bearing on operations that occur after it. It is not just a service endpoint for a database, it is a methodology that pushes state management to the client. Ultimately REST is more about how data is transferred than it is about what that data is. So: 1. Bandwidth is bandwidth, but the average entity will not eat very much. It's perfectly fine to send a whole entity down the pipe if you need to. Be mindful that sensitive properties are not sent (tag with JsonIgnore if using JSON.NET eg. Newtonsoft, etc). That's not the case for arrays of entities, page those as appropriate on the server side. 2. ViewModels are your very best friend. Well, they're mine, anyway. 3. Completely immaterial. As long as the transaction can be done in an atomic manner you can do what you're most comfortable with. That said, ViewModels are my very best friend, as previously mentioned. There is a pretty solid primer on IBM: http://www.ibm.com/developerworks/library/ws-restful/[^]
-
I think you're misinterpreting the meaning of a REST service. The primary key is that the server itself should be stateless; each transaction must be atomic, having nothing to do with the ones before it, and no bearing on operations that occur after it. It is not just a service endpoint for a database, it is a methodology that pushes state management to the client. Ultimately REST is more about how data is transferred than it is about what that data is. So: 1. Bandwidth is bandwidth, but the average entity will not eat very much. It's perfectly fine to send a whole entity down the pipe if you need to. Be mindful that sensitive properties are not sent (tag with JsonIgnore if using JSON.NET eg. Newtonsoft, etc). That's not the case for arrays of entities, page those as appropriate on the server side. 2. ViewModels are your very best friend. Well, they're mine, anyway. 3. Completely immaterial. As long as the transaction can be done in an atomic manner you can do what you're most comfortable with. That said, ViewModels are my very best friend, as previously mentioned. There is a pretty solid primer on IBM: http://www.ibm.com/developerworks/library/ws-restful/[^]
Thanks a lot for your reply, Nathan. It answers my questions very clearly. The IBM article is also very useful. I will have to keep going back to it any time I forget what REST is when I get bogged down by implementation details. :D