3

I'm new to web API design, so I've tried to learn best practices of web API design using these articles:

1.Microsoft REST API Guidelines

2.Web API Design-Crafting Interfaces that Developers Love from "Apigee"

Apigee is recommending web API developers to use these recommendations to have better APIs. I quote here two of the recommendations: I need C# code for implementing these recommendations in my Web APIs (in ASP Core) which is a back-end for native mobile apps and AngularJs web site.

  1. Sweep complexity behind the ‘?’ Most APIs have intricacies beyond the base level of a resource. Complexities can include many states that can be updated, changed, queried, as well as the attributes associated with a resource.

Make it simple for developers to use the base URL by putting optional states and attributes behind the HTTP question mark. To get all red dogs running in the park:

GET /dogs?color=red&state=running&location=park

  1. Partial response allows you to give developers just the information they need.

Take for example a request for a tweet on the Twitter API. You'll get much more than a typical twitter app often needs - including the name of person, the text of the tweet, a timestamp, how often the message was re-tweeted, and a lot of metadata.

Let's look at how several leading APIs handle giving developers just what they need in responses, including Google who pioneered the idea of partial response.

LinkedIn

/people:(id,first-name,last-name,industry)

This request on a person returns the ID, first name, last name, and the industry.

LinkedIn does partial selection using this terse :(...) syntax which isn't self-evident.

Plus it's difficult for a developer to reverse engineer the meaning using a search engine.

Facebook

/joe.smith/friends?fields=id,name,picture

Google

?fields=title,media:group(media:thumbnail)

Google and Facebook have a similar approach, which works well.

They each have an optional parameter called fields after which you put the names of fieldsyou want to be returned.

As you see in this example, you can also put sub-objects in responses to pull in other information from additional resources.

Add optional fields in a comma-delimited list

The Google approach works extremely well.

Here's how to get just the information we need from our dogs API using this approach:

/dogs?fields=name,color,location

Now I need C# code that handles these kind of queries or even more complex like this:

api/books/?publisher=Jat&Writer=tom&location=LA?fields=title,ISBN?$orderBy=location desc,writerlimit=25&offset=50

So web API users will be able to send any kind of requests they want with different complexities, fields, ordering,... based on their needs.

Sepidehye Fanavari
  • 83
  • 8
  • It is unclear what you are asking. Do note that routing does not use the query string at all unless you customize it to do so. Routing *only* considers the path (e.g. `/foo/bar`) to get a match. The query string data is only considered after matching the route - but query string data is passed into action methods by [value providers](http://stackoverflow.com/a/36606015/181087), not by routes. – NightOwl888 Jul 26 '16 at 15:09
  • You can use OData V4 to implement this http://www.asp.net/web-api/overview/odata-support-in-aspnet-web-api/odata-v4/create-an-odata-v4-endpoint – Paresh Jul 26 '16 at 16:25
  • @ NightOwl888 I changed the post to explain what I mean. Thanks – Sepidehye Fanavari Jul 27 '16 at 15:45
  • @Paresh 2. I'm new to web API design. My project is really big and I'm looking for best practices. Is using OData better than implementing query handling manually? 2. I think you're suggesting that I use regular web api and when I need to handle query strings, use Odata. 3. Unfortunately when I tried to add "Microsoft.AspNet.Odata" (v 5.9.1) nugget package, I get this error "is not compatible with netcoreapp1.0 (.NETCoreApp,Version=v1.0)" I also tried adding package "Microsoft.AspNet.WebApi.Odata" but I got the same error. – Sepidehye Fanavari Jul 27 '16 at 15:51
  • @SepidehyeFanavari 1. It depends on your case, if you have complex domain model then it may not be the best solution for you. 2. No I was suggesting to use OData for all your controllers but again this is depends on your project complexity. 3. You need to use OData 6.0.0 alpha package for ASP core. Here are some useful links http://odata.github.io/WebApi/#07-07-6-0-0-alpha1 http://myget.org/gallery/odatavnext https://github.com/OData/WebApi/tree/v6.0.0-alpha1/vNext/samples/ODataSample.Web – Paresh Jul 27 '16 at 16:17

0 Answers0