As i'm new to REST APIs, I'm trying to create an application that exposes an api as follows:-
public class CreateAccount
{
public int ClientAccountID { get; set; }
public string Name { get; set; }
public string Email { get; set; }
public string CountryCode { get; set; }
public string LanguageCode { get; set; }
public string FleetType { get; set; }
}
public HttpResponseMessage PostAccount(CreateAccount newAccount)
{
/*doing stuff after getting newAccount object*/
}
Now I want to implement enumerated values in FleetType so that client can enter only one value out of these specific values as ("string1", "string2","string3") for FleetType.
Instead of just throwing a status code, you may also want to throw in a helpful string with it. That is in the API side and that can act as your error message to the user.
Now in the client side, if you are using .NET, you can use the HttpClient.EnsureSuccessStatusCode() method to make sure that the status code is not an error. If the status code is an error, it will (surprise!) throw an exception.
If you are using Javascript as your client, then you can use jQuery. You can also specify what to do if, for example, you received a 404, 400 or a 500. Check out a tutorial here:
But my concern with using web-api is that here client doesn't know the exact syntax for using my exposed web APIs because there is no help page functionality, so client will first send request and then if its not okay with my API syntax then they'll receive
response exception.
While in WCF because of help page, client can easily frame their request to server.
agarwal.peeu...
Member
12 Points
32 Posts
Creating PostAccount(Object newObject)
Jul 27, 2012 07:09 AM|LINK
Hello,
As i'm new to REST APIs, I'm trying to create an application that exposes an api as follows:-
public class CreateAccount { public int ClientAccountID { get; set; } public string Name { get; set; } public string Email { get; set; } public string CountryCode { get; set; } public string LanguageCode { get; set; } public string FleetType { get; set; } } public HttpResponseMessage PostAccount(CreateAccount newAccount) { /*doing stuff after getting newAccount object*/ }Now I want to implement enumerated values in FleetType so that client can enter only one value out of these specific values as ("string1", "string2","string3") for FleetType.
Kindly suggest on this.
pacoalphonso
Member
138 Points
63 Posts
Re: Creating PostAccount(Object newObject)
Jul 27, 2012 07:22 AM|LINK
Three ways to do this:
1) In your consumer project (the one that will call the Web API), check the FleetType. If it is not valid, then handle the error.
2) In your web api project, check for the validity. If it is not valid, then send back an exception to the client.
3) Implement a combination on both consumer project and web api project.
For me, I would go with number three.
Hope this helps
agarwal.peeu...
Member
12 Points
32 Posts
Re: Creating PostAccount(Object newObject)
Jul 27, 2012 08:21 AM|LINK
Thanks for the response.
Can we get help page in web api project, similar to WCF rest services gives.
This can help clients to understand what is required in request for consuming APIs.
Kindly suggest as this would be helpful for me.
pacoalphonso
Member
138 Points
63 Posts
Re: Creating PostAccount(Object newObject)
Jul 27, 2012 08:33 AM|LINK
I believe you're going to have to implement the help pages. However, it is possible to give back an HttpResponseMessage<t> from the API to the client.
For example, you could assign an exception to that class, like this: HttpResponseMessage<CustomErrorException>
and then, throw an HttpStatus code along with it.
Reply here if you want some sample code
agarwal.peeu...
Member
12 Points
32 Posts
Re: Creating PostAccount(Object newObject)
Jul 29, 2012 03:01 PM|LINK
Yeah thanks for the help.
But don't we have like a help page that would suggest client to request in a correct syntax... What is required and what is the data type?
It would be good if you can give me some link towards a tutorial or sample code.
Thanks
pacoalphonso
Member
138 Points
63 Posts
Re: Creating PostAccount(Object newObject)
Jul 30, 2012 09:09 AM|LINK
Check this out - it teaches you how to use HttpResponseException:
http://stackoverflow.com/questions/10660721/what-is-the-difference-between-httpresponsemessage-and-httpresponseexception
Instead of just throwing a status code, you may also want to throw in a helpful string with it. That is in the API side and that can act as your error message to the user.
Now in the client side, if you are using .NET, you can use the HttpClient.EnsureSuccessStatusCode() method to make sure that the status code is not an error. If the status code is an error, it will (surprise!) throw an exception.
If you are using Javascript as your client, then you can use jQuery. You can also specify what to do if, for example, you received a 404, 400 or a 500. Check out a tutorial here:
http://api.jquery.com/jQuery.ajax/
agarwal.peeu...
Member
12 Points
32 Posts
Re: Creating PostAccount(Object newObject)
Jul 31, 2012 10:04 AM|LINK
Thanks for the response.
But my concern with using web-api is that here client doesn't know the exact syntax for using my exposed web APIs because there is no help page functionality, so client will first send request and then if its not okay with my API syntax then they'll receive response exception.
While in WCF because of help page, client can easily frame their request to server.
Thanks
pacoalphonso
Member
138 Points
63 Posts
Re: Creating PostAccount(Object newObject)
Aug 03, 2012 07:36 AM|LINK
agarval.peeush,
I just saw some blog posts in MSDN by Mr. Yao regarding Web API documentation. You may want to look at it. Here's the link:
Part 1 of his blog http://blogs.msdn.com/b/yaohuang1/archive/2012/05/13/asp-net-web-api-introducing-iapiexplorer-apiexplorer.aspx
Part 2 of his blog http://blogs.msdn.com/b/yaohuang1/archive/2012/05/21/asp-net-web-api-generating-a-web-api-help-page-using-apiexplorer.aspx
John Petersen's blog extending what Mr. Yao started http://codebetter.com/johnvpetersen/2012/08/01/documenting-your-asp-net-web-apis/
Hope this helps