WCF REST -->Client<-- (not a service)
Unfortunately, I am forced into a situation where I need to make calls against URIs that do not comply with the 'name=value' standard.
Basically, I need to (GET)...
http://host/resource/method/?filter=some.thing={value}
...which has compound values.
This translates instead of a 'name=value' pair to 'name=value=value' token, which does not correspond to RFC 6570 and is rejected by the WCF UriTemplate class.
I'm already using several (client) WCF extensibility points, but I'm not enough of a black-belt to know precisely whether or not its possible to make a call such as the one noted above, and if so: where do I inject it?
Attempts to URL encode my way around this thus far have not worked (the server ignores my client query).
Any help is greatly appreciated. I'm banging my head against the wall with this.
The error of course is:
"The UriTemplate '?filter=some.thing={value}' is not valid; each portion of the query string must be of the form 'name=value', when value cannot be a compound segment. See the documentation for UriTemplate for more details."
I hope folks like Carlos Figueira are watching... :)
Warmest regards
Related
This question already has answers here:
What is the restful way to represent a resource clone operation in the URL?
(5 answers)
Closed 7 years ago.
I am writing a YAML document using swagger to design a RESTful API method for cloning a resource. I have a few options and don't know which would be best. Please can someone advise?
Options:
Relinquishing the responsibility of cloning the resource object to the consumer (where the consumer assigns values to properties on a new object and then creates a new object), the process would need to consist of two requests to the API: a GET against a resource for the source object and then a POST to that resource for creating the new one. This feels like the consumer has too much responsibility.
Using the WebDAV HTTP extensions which provides a COPY method (see here). It would appear that this is exactly what I would like for cloning. However, I would like to stick to the standard methods as much as possible
POSTing to /{resource}?resourceIdToClone={id} where resourceIdToClone is an optional parameter. This would conflict with an API path that I already have for creating the resource, where I add a schema to the POST body. It would mean using a POST to /{resource}/ for creating and cloning, and that would violate SRP.
Adding a new resource called 'CloneableResource' and performing a POST to /CloneableResource/{resource_type}/{resource_source_id}. For the example of cloning a sheep, you'd make a POST to /CloneableResource/Sheep/10. This way, it would be possible to stick to using the standard HTTP methods, there'd be no conflict with any other resource paths (or SRP violation). However, I would be adding a new and potentially superfluous type to the domain. I also can't think of a scenario when a consumer would want to perform anything other than a POST to this resource, so it seems like a code smell to me.
A GET against /resource/{id}?method=clone. One of the advantages here is that no additional resource is required and it may be determined by a simple optional querystring parameter. I'm aware that one of the risks here is that it can be dangerous to provide post or delete capabilities using a GET method if the URL is in a web page as it may be crawled by a search engine.
Thanks for any help!
Most of these options are perfectly good choices. A lot of it just your style choice in the end. Here are my comments on each of your options.
Relinquishing the responsibility of cloning the resource object to the consumer
In general I don't really have a problem with this solution. This option is very straight forward for a user to understand and implement. It might be better than coming up with some proprietary cloning functionality that your users have to learn how to use.
Using the WebDAV HTTP extensions which provides a COPY method
I like to stick to the standard methods as well. I would not use COPY, but I wouldn't appalled if you did.
POSTing to /{resource}?resourceIdToClone={id}
This is a perfectly good solution. From a REST standpoint, you don't really have a conflict with the rest of your API. The URI with a query parameter identifies a different resource than the URI without the query parameter. Query parameters are a URI feature for identifying resources that you can not be referenced hierarchically. However, it might be difficult to separate these in your code because of the way most REST frameworks work. You could do something similar to this except with a hierarchical URI such as /{resource}/clone. You could POST to this URI and pass the resource_source_id in the body.
Adding a new resource called 'CloneableResource' and performing a POST to /CloneableResource/{resource_type}/{resource_source_id}
There is nothing wrong with this approach from a REST standpoint, but I think adding a new type is both unnecessary and clutters the API. However, I disagree with your intuition there could be problem with having a resource that has only a POST operation. It happens. In the real world, not everything fits nicely into GET, PUT, or DELETE.
A GET against /resource/{id}?method=clone
This is the only option of the 5 that I can not condone. It seems from your description that you already understand why this is a bad idea, so I'm not sure why you are considering it. However, all you have to do to make this a good solution is to change GET to POST. It then becomes very similar to the #3 solution. The URI could also be hierarchical instead of using a query parameter. POST /resource/{id}/clone would work just as well.
I hope this was helpful. Good luck with your decision.
If you want to COPY a resource, then, yes, COPY is an obvious choice.
(and yes, it would be good to pull the definitions of COPY and MOVE out of RFC 4918 to untangle them from WebDAV).
Influenced by project requirements and the range of preferences amongst members in my team, option 1 will serve us best at this stage.
Conforming to the standard HTTP methods will simplify and clarify my API
There will be a single, consistent approach to cloning a resource. This outweighs the issue I have with designating the cloning work to the consumer.
I am wanting to setup a REST API with a legacy database. I am looking into LINQ to SQL as an option to be the communicator between the database and the REST API. The order of operations are as follows: client will request data from REST API, REST API receives the "GET" request, calls LINQ to SQL method to get the object requested, object is returned in JSON format to client for client-side processing. I like LINQ to SQL because it can take a data table and spit out a C# object.
Most of the requests will be "GET"; however, in the future "POST" and "PUT" will be added.
Is this reasonable, or should I look to a different method? I am a new developer, so please excuse my ignorance!
The particular technologies that you use are just tools that help you achieve a goal. A means to an end. That goal is typically to solve some business problem. It is also good to do so in a robust, flexible and easily extensible way so as to provide the most possible business value in the least amount of time.
If one were to analyze an aspect of your question, using LINQ to SQL is fine. However, there are any number of ORM solutions that would accomplish a similar result (nHibernate, Entity Framework, ADO.NET). They all can achieve the goal of solving the business problem.
The important thing to remember is that the specific technology you choose for an implementation is typically not nearly as important as how you go about implementing the solution. Good and bad code are independent of technology they are written in.
In summary, the technologies that you listed in your question are all excellent technologies that can provide robust, flexible, and easily extensible solutions when used properly.
In most tutorials, documentation, articles etc. about RESTful I come across a few of the same points, but yet I rarely ever see these 'What makes it RESTful' points implemented.
For example, I've read this many times:
Content type
Using HTTP headers
Accept: application/json, text/plain
Extension in the URL
Not RESTful, URLs are not the place for Content-Type
I have never come across an API where I have seen this implemented. Every API I have ever used has always required me to append XML or JSON to the end of the URL. Are they doing it wrong?
Versioning
Version media types
application/vnd.something.v1+json
Custom header
X-API-Version: 1
Version in URL
/v1/resouce
Not RESTful, by putting the version in the URL you create separate resources
If you need to introduce non-backwards-compatible functionality surely creating a seperate resource is the correct thing to do?
Once again, in all versions of APIs I've used, they use v1, v2 in the URL (such as google, imgur etc.)
By not implementing these points, would my API not be considered RESTful?
To clarify these points would be much appreciated.
1) Using accept header or using format specific URLs are both valid in a RESTful system. The article you are citing is wrong.
2) Saying v1/resource is not RESTful is also incorrect. You cannot look at a URI and make a conclusion about its RESTfulness. Adding a v1 at the root of your URL is probably not a great thing to do if you are trying to incremental evolve your system. In effect it declares a whole new URL space and obsoletes the old one. That's pretty drastic. RESTFul systems try and enable incremental and evolutionary change to a system. So doing /resource/v2 is actually much more compatible with that goal.
The unfortunate phenomena at work here is that many developers who are learning about REST discover that the vast majority of systems out there that claim to be doing REST are not actually conforming to the constraints of REST. So they quickly develop a zeal for telling everyone what is and is not RESTful. Many of these people have not yet fully understood the constraints and end up making up new ones that don't exist. The "RESTFul URL" fallacy is a classic. "POST must create a resource" is another common one.
My guidance to anyone learning REST is, if someone tells you that something is not RESTful, you ask them what constraint it is violating and what is the practical impact of ignoring that constraint. If they can't answer that, then politely ignore them.
The true definition of REST is obviously in the doctoral dissertation written by Roy Fielding in 2002. Do all of the API's out there that call themselves RESTful follow the guidelines specified by Fielding? The answer is no. The definition of REST has been watered down by some to just mean anything that does not use SOAP. I would worry less about what is RESTful and more about what is good practices. It is a good practice to specify the content type in the header of the request. It is also a good practice to version your API's. A good resource for information on API best practices is from the guys at Apigee as they have a lot of experience in this area. Check out their webinar on RESTful API Design where they ask if you are a pragmatist or a RESTafarian.
I would like to know, in a nutshell, a summary of the limitations of using OData from the point of view of the query. For example:
Can I do recursive queries?
What subset of LINQ features it includes?
I found that the specs are very long to analyze.
Well, when you ask about the query limitations of OData, I think you mean the limitations of WCF Data Services. OData is the protocol; the implementation of what's supported or not in conjunction with the syntax and operation keywords of the OData protocol is up to the OData provider (which is WCF Data Services in your case, I believe since you tagged the question as WCF).
Given that, the subset of LINQ features are spelled out in this MSDN article. The number of limitations is pretty substantive, so it's probably better to just link to it instead of listing them out.
For your first question about recursive queries, I have to admit I'm not sure of how a typical LINQ recursive function would look like, unless you define your own extension method. If you're doing something like that, your best bet may be to wrap that recursive call in a WCF Data Service custom service method and invoke it via the URL as you would any other service method.
I hope this helps!
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
I am planning on putting up a web service, or some other service exposed over the internet. I would like to create an API for applications to interact with this service. I would like the API to be usable in different languages, such as Java, C++, C#, or PHP. How can I maintain one code base for my API, but distribute nice packaged binaries for all these languages? Also, I may want to consider this could be cross platform as well.
Update 1
I'm early days on Web Services, but I
think one of the key points is that
lots of tooling supports the
implementation of clients based on the
description of the service like WDSL.
I've not delivered any client-side
software with anything I've done, I
expect any user to be able to build
their own clients suited to their
needs. --Brabster's Answer
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
Update 2
As far as expecting the client that is
using your API to do anything, you
can't! There is nothing you will be
able to do to ensure that the consumer
of the API will do anything right.
That's why robust error handling is so
important. You must check and double
check any and everything that comes
from the client. You must always be
suspicious of it, and even assume that
it is malicious. There really is no
good way around that fact. --Ryan Guill's Answer
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
Update 3
I have accepted Ryan Guill's answer. I think the general idea is that I need to expose a network service of some sort, with the lowest barrier to the client. That way anyone can connect. Then just have all my code run on the server. That seems to be accepted as the only want to really achieve the platform and language independence I am after.
Thanks for all the input.
I would use a REST API, similar to the way Flickr's API works: http://flickr.com/services/api/
It is fairly simple to create and maintain, the biggest downsides are that it takes a lot of documentation (but pretty much any way you do an API will have this issue) and that robust error handling is a must.
But in my opinion, it's the best way to create an API that is the closest to cross platform/cross language.
More information here: http://www.xfront.com/REST-Web-Services.html
Update: The submitter added the following to the post:
I am not opposed to making it a straight web service then giving out a WSDL file. But what if I want the client API to do some logic, encryption, error checking or so on?
I personally do not like using SOAP (using a WSDL). There is a lot of inherent overhead to using SOAP, both on the server and the client. I think that is why you see more and more public API's being written using REST. It really lowers the barrier to entry to the lowest common denominator, allowing anything that can use basic HTTP (GET and POST (also PUT and DELETE for the "proper" way of doing it)) to use the API.
Some more examples of public API's written using REST: twitter, vimeo, Google
As far as expecting the client that is using your API to do anything, you can't! There is nothing you will be able to do to ensure that the consumer of the API will do anything right. That's why robust error handling is so important. You must check and double check any and everything that comes from the client. You must always be suspicious of it, and even assume that it is malicious. There really is no good way around that fact.
Update 2: the submitter added the following to the post:
My original idea was to create a DLL or Assembly in .NET, then the client is making calls into this code that is running client side. This code may talk via any communications protocol back to the server, but my API would be running on their box. I guess REST does not really accomplish this. It seems like in REST everything is still an HTTP post. It is almost web services with out soap.
You can certainly do this, but that is only going to work for .NET languages, meaning that your cross-platform and cross-language benefits are out the window. And still, in the end, are you really preventing anything? The developer is going to either use your remote API, or your local DLL or Assembly. Either way, he is going to have to know how to use it and use it right, otherwise you are going to throw an error. All you are really doing is changing where the errors get thrown from. Which may be important to you (if so, mention why) but really isn't changing anything in the equation.
But you are somewhat correct in saying REST is kind of like web-services without the SOAP. Technically REST is web-services too, its just that web-services have come to generally mean SOAP. It really is a different way of achieving the same thing. The biggest differences are though that it takes more programming and thought on your side (and potentially more programming on the client side) but you trade that for robustness, less overhead in both the consumer and the server, and the widest possible audience for the API. It really is the lowest common denominator.
I'm early days on Web Services, but I think one of the key points is that lots of tooling supports the implementation of clients based on the description of the service like WDSL.
I've not delivered any client-side software with anything I've done, I expect any user to be able to build their own clients suited to their needs.
If you check out the flickr API as suggested by one of your other answers, I don't think they supply client side code, other people have built and contributed client side stuff.
I suggest writing the API in the Haxe programming language so that the source code can be directly translated to all the programming languages you mentioned. The Haxe programming language can be translated (or "trans-compiled") to all of the programming languages that you mentioned in the original post, as well as a few others.
Simple answer, no.
Complex answer: create an API and compile it to a COM dll. Then, just build the wrapper code for the languages that can't handle that.
Simple answer #2, make the original service so trivial, or so universally acceptable, as to not require an API (I usually implemented this through server-side database polling. Ugly but any language that can access a database can utilize the program).