Introduction To REST and PDF

9/20/2017 Introduction to REST and .
net Web API – Martin Kearn
This site uses cookies for analytics, personalized content and ads. By continuing to browse this site, you agree to this use. Learn more (https://go.microsoft.com/fwlink/?linkid=845480)
(http://msdn.microsoft.com/)| Developer
Introduction to REST and .net Web API

Rate this article ★
★★★★
★★
★★★★★
★★★
Martin Kearn (https://social.msdn.microsoft.com/profile/Martin+Kearn) January 5, 2015
 30 (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comments)
If you are building apps or websites today, the chances are you’ll have heard of REST and .net Web API, but you may not Share 30 12 22
be sure what these things are, whether you should use them or how to get started. If this sounds familiar, then this article
for you.
API; what and why?

Let’s start right at the start and figure out what an API is and why you should consider using one.
The term API stands for ‘Application Programming Interface’. In the world of web development the term ‘API’ is
synonymous with online web services which client apps can use to retrieve and update data. These online services have
had several names/formats over the years such as SOAP, however the current popular choice is to create a REST (or
RESTful) API.
We’ll come onto REST and why REST is now preferred later, but first let’s examine why you would even bother with an
API.
Let’s consider a modern application which may include several mobile apps on various platforms and usually some kind
of web application too. Without an API, a basic architecture may look like this where each client app has its own
embedded business logic.
(https://msdnshared.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Blogs.Components.WeblogFiles/00/00/00/56/73/3225.NoAP
Notice that each client app has its own embedded business logic (probably written in several different languages) which
connects directly to the database to get, update and manipulate data. This local business logic means that the client apps
can easily become complex and all need to be maintained in sync with each other. When a new feature is required, you’ll
have to update each app accordingly. This can be a very expensive process which often leads to feature fragmentation,
bugs and can really hold back innovation.
https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/ 1/40
9/20/2017 Introduction to REST and .net Web API – Martin Kearn
Now let’s consider the same architecture with a central API which hold all the business logic.
(https://msdnshared.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Blogs.Components.WeblogFiles/00/00/00/56/73/2318.WithA
Each app uses the same API to get, update and manipulate data. All apps have feature parity and when you need to
make a change you just make it in one place in line with the ‘Don’t Repeat Yourself’ (DRY) principle of software
development. The apps themselves then become relatively lightweight UI layers.
Happy Days
What is REST?
REST stands for ‘Representational State Transfer’ and it is an architectural pattern for creating an API that uses HTTP as its
underlying communication method. REST was originally conceived by Roy Fielding in his 2000 dissertation paper entitled
‘Architectural Styles and the Design of Network-based Software Architectures’, chapter 5 cover REST specifically:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
(http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
Almost every device that is connected to the internet already uses HTTP; it is the base protocol that the internet is built
on which is why it makes such a great platform for an API.
HTTP is a request and response system; a calling client sends a request to an endpoint and the endpoint responds. The
client and endpoint can be anything but a typical example is a browser accessing a web server or an app accessing and
API.
There are several key implementation details with HTTP that you should be aware of:
Resources – REST uses addressable resources to define the structure of the API. These are the URLs you use to get
to pages on the web, for example ‘http://www.microsoft.com/Surface-Pro-3’ is a resource
Request Verbs – These describe what you want to do with the resource. A browser typically issues a GET verb to
instruct the endpoint it wants to get data, however there are many other verbs available including things like POST,
PUT and DELETE. See the full list at http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)
Request Headers – These are additional instructions that are sent with the request. These might define what type
of response is required or authorisation details. See the full list at http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
Request Body - Data that is sent with the request. For example a POST (creation of a new item) will required some
data which is typically sent as the request body in the format of JSON or XML.
Response Body – This is the main body of the response. If the request was to a web server, this might be a full
HTML page, if it was to an API, this might be a JSON or XML document.
Response Status codes – These codes are issues with the response and give the client details on the status of the
request. See the full list at www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)
In the context of a REST API, resources typically represent your data entities (i.e. ‘Product’, ‘Person’, ‘Order’ etc). The verb
that is sent with the request informs the API what to do with the resource, for example a GET request gets data about an
entity, POST requests create a new entity.
There is a convention in place that GET requests to an entity url such as /Products returns a list of products, possibly
matching some criteria that was sent with the request. However, to retrieve a specific product, you would use the
product’s ID as part of the resource, for example /Products/81 would return product with the ID of 81. It is also possible
to use query string parameters with an API, for example you may have something like /Products?Colour=red which
returns all red products.
These are some typical requests you might expect to see in an ecommerce API:
Response
Resource Verb Expected Outcome
Code
/Products GET A list of all products in the system 200/OK
A list of all products in the system where the colour is
/Products?Colour=red GET 200/OK
red
/Products POST Crea on of a new product 201/Created
/Products/81 GET Product with ID of 81 200/OK
/Products/881(a product ID which does not 404/Not
GET Some error message
exist) Found
204/No
/Products/81 PUT An update to the product with an ID of 81
Content
204/No
/Products/81 DELETEDele on of the product with an ID of 81
Content
/Customers GET A list of all customers 200/OK
What is .net Web API?

.Net’s Web API is an easy way to implement a RESTful web service using all of the goodness that the .net framework
provides. Once you understand the basic principles of REST, then a .net Web API will be very easy to implement.
Web API is built on .net’s modular, pluggable pipeline model. This means that when a server hosting a web API receives a
request, it passes through .nets request pipeline first. This enables you to easily add your own modules if you find that
the default capabilities are not enough for your needs. With the recent announcements on ASP.net vNext this also means
you can potentially host your Web API outside of Windows Server which opens up a whole range of usage cases. See
http://www.asp.net/vnext (http://www.asp.net/vnext) for detail.
Web API uses the Controller and Action concepts from MVC so if you already understand .net MVC you are in a good
place. If you don’t, then Web API is a great way to learn MVC.
Resources are mapped directly to controllers; you would typically have a different controller for each of your main data
entities (Product, Person, Order etc). Web API uses the .net routing engine to map URLs to controllers. Typically, APIs are
held within a ‘/api/’ route which helps to distinguish API controllers from other non-API in the same website.
Actions are used to map to specific HTTP verbs, for example you would typically have a GET action which returns all of
the entities. This action would respond to /api/Products (where ‘products’ is your controller) and would look something
like this:
public IEnumerable<string> Get()

{
return new string[] { "value1", "value2" };
}
You may also have a GET action which accepts a specific ID and returns a specific entity. It would respond to
/api/Products/81 and would look something like this:
public string Get(int id)

{
return "value";
}
There are many great hidden benefits to using Web API which you may not realise but actually save you a lot of work.
Web API is part of ‘One ASP.net’

Web API is part of the ‘One ASP.net’ family which means that it natively supports all of the great shared features you may
currently use with MVC or web forms, this includes (these are just a few examples):
Entity Framework
Authorisation and identity
Scaffolding
Routing
Serialization and Model Binding

Web API is setup by default to provide responses in either XML or JSON (JSON is default). However, as a developer you
do not need to do any conversion or parsing – you simply return a strongly typed object and Web API will convert it to
XML or JSON and return it to the calling client, this is a process called Content Negotiation. This is an example of a GET
action which returns a strongly typed Product object.
public Product GetProduct(int id)

{
var product = _products.FirstOrDefault(p => p.ID == id);
if (product == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
return Request.CreateResponse(HttpStatusCode.OK, product);
}
This also works for incoming requests using a feature called Model Validation. With Model Validation, Web API is able to
validate and parse incoming response body data to a strongly typed object for you to work with in your code. This is an
example of model binding:
public HttpResponseMessage Post(Product product)

{
if (ModelState.IsValid)
{
// Do something with the product (not shown).
return new HttpResponseMessage(HttpStatusCode.OK);

}
else
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
}
}
Dynamic API Help Pages

If you choose Web API as your project type, when you first create your project, you will get automated documentation
with your API. This is a regular MVC project that sits alongside your API. The help pages project looks at your API code,
models, attributes etc and constructs documentation automatically, which includes examples, model definitions and
more.
This documentation makes for a great resource to help developers of calling client understand the structure of your API.
Help pages are contained within a route called ‘/help/’.
In Summary
To summarise, use of an API will make the architecture of your application much cleaner, making it easier to add features
and fix bugs as your project progresses.
REST is an architectural pattern which is based on HTTP and uses HTTP requests, responses, verbs and status codes to
communicate. The fact that REST services use HTTP means they can be consumed by almost any ‘online’ device or
application (including IoT devices such as toasters, cars, pedometers etc) – no proprietary knowledge of the API is
required.
Web API in .net is the way you write REST APIs services in .net. Web API gives you all the benefits of the .net framework
and deals with a lot of the complexities of content negotiation, model binding etc that you’d have to deal with yourself
without Web API.
To get started with Web API, I’d recommend you initially take a look at my 6 minute video which talks through the
process of creating a very simple web API: https://aka.ms/mk-filenewapivideo (https://aka.ms/mk-filenewapivideo)
Then you should take a look on the official ASP.net sub site which has plenty of tutorials, examples and videos:
http://www.asp.net/web-api (http://www.asp.net/web-api)
Tags api (https://blogs.msdn.microsoft.com/martinkearn/tag/api/) asp.net (https://blogs.msdn.microsoft.com/martinkearn/tag/asp-net/) rest

(https://blogs.msdn.microsoft.com/martinkearn/tag/rest/) Web API (https://blogs.msdn.microsoft.com/martinkearn/tag/web-api/)
Comments (30)
Name *
Email *
Website
Post Comment
Osman
April 15, 2016 at 2:29 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3237)
This is an amazing article, I appreciate it.
Reply (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/?replytocom=3237#respond)
Osman
April 15, 2016 at 2:29 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3235)
This is an amazing article, I appreciate it.
Ash
May 6, 2016 at 1:26 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3295)
So far this the Best article I found which clearly explains diff between REST and Web APIs. Thank you so much!!!
Ian
As a BSA having to learn and document web service requirements, this is really appreciated. It’s so clearly written and the links to other resources
are all good.
Zaheer Mirza
Awesome and Useful!
Arunkumar
May 19, 2016 at 9:40 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3347)
Good article, very helpful.
Nazli
June 7, 2016 at 3:16 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3495)
This was so helpful, So simple and at the same time covers everything we should know about Web API.
I appreciate it.
ritesh
very useful, thanks!
Arun
June 19, 2016 at 5:46 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3685)
Very useful content for the Web API
Raed
Helpful article.
Is there any official course from microsoft for API and REST ?
Sumesh
Nice article. Gives a clear overview about Rest and webapi to dummies.
Couple of semantic corrections :
1. PUT verb is used to create resource and POST to update. The article specifies vice versa.
2. Under the Model validation, it is the request that is being validated and not response.
Though it is easy to infer them correctly, it would be good to correct them
ganesh kumar
Excellent article with crisp explanation on Web API’s and REST principles
Ross
Good article!
John
July 3, 2016 at 1:02 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3775)
Many thanks for the easy explanations
Cristobal
July 14, 2016 at 10:15 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3795)
Very useful article! Thanks
Sovi (https://psovit.wordpress.com/)
July 18, 2016 at 12:24 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3825)
Very well written article. I like how you have discussed the concepts of RESTFul web and API concisely in such a short article.
Dessa
July 19, 2016 at 6:45 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-3855)
This sort of overview is exactly what I’ve been looking for. Thank you SO much,.
divine dela
August 22, 2016 at 11:14 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4025)
This is the best introductory article i have found on REST and .net Web API. Your diagrams communicated a lot.
Prabhakar kumar priyadarshi

August 23, 2016 at 3:33 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4035)
Finally, I am able to understand Api, restfull .greate articles kudos for you
Syed Rahim
August 25, 2016 at 10:18 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4055)
excellent articles
binu
September 1, 2016 at 2:06 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-
4075)
Very good article. Simple to understand. Thanks.
Murtaza Jaffari
4145)
Great article !!
Edalat
4195)
This is an amazing article, Describes web api architecture very good.thanks
Abdul Rauf (http://allinterviewquestions.net)

4225)
Amazing
Mahendra
October 9, 2016 at 3:18 pm (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4365)
This article gives you the clear picture of what is REST and Web API.
Aprian
October 12, 2016 at 8:57 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4376)
Thank you, the world needs a man like you.
Nikhil
Nice…Very Useful
nair (http://www.home.com)
No doubt! Precise and Prefect!
TRiz
October 27, 2016 at 3:49 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-4465)
Concise and Informative.
Hanieh
November 6, 2016 at 9:22 am (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/#comment-
4555)
thanks an ocean , you wrote so well….
Follow Us
 (https://blogs.msdn.microsoft.com/martinkearn/feed/)
Popular Tags
asp.net (https://blogs.msdn.microsoft.com/martinkearn/tag/asp-net/) azure (https://blogs.msdn.microsoft.com/martinkearn/tag/azure/)
api (https://blogs.msdn.microsoft.com/martinkearn/tag/api/) Installation (https://blogs.msdn.microsoft.com/martinkearn/tag/installation/)
web development (https://blogs.msdn.microsoft.com/martinkearn/tag/web-development/)
Cognitive Services (https://blogs.msdn.microsoft.com/martinkearn/tag/cognitive-services/)
Machine Learning (https://blogs.msdn.microsoft.com/martinkearn/tag/machine-learning/)
Web API (https://blogs.msdn.microsoft.com/martinkearn/tag/web-api/) rest (https://blogs.msdn.microsoft.com/martinkearn/tag/rest/)
cloud hero challenge (https://blogs.msdn.microsoft.com/martinkearn/tag/cloud-hero-challenge/)
Architecture (https://blogs.msdn.microsoft.com/martinkearn/tag/architecture/)
visual studio (https://blogs.msdn.microsoft.com/martinkearn/tag/visual-studio/)
Asp.Net 5 (https://blogs.msdn.microsoft.com/martinkearn/tag/asp-net-5/)
Project Oxford (https://blogs.msdn.microsoft.com/martinkearn/tag/project-oxford/)
Shared Services (https://blogs.msdn.microsoft.com/martinkearn/tag/shared-services/)
Entity Framework (https://blogs.msdn.microsoft.com/martinkearn/tag/entity-framework/)
visual studio 2015 (https://blogs.msdn.microsoft.com/martinkearn/tag/visual-studio-2015/)
Future Decoded (https://blogs.msdn.microsoft.com/martinkearn/tag/future-decoded/)
Performance (https://blogs.msdn.microsoft.com/martinkearn/tag/performance/)
Document Management (https://blogs.msdn.microsoft.com/martinkearn/tag/document-management/)
Archives
March 2017 (https://blogs.msdn.microsoft.com/martinkearn/2017/03/) (1)
November 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/11/) (1)
October 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/10/) (1)
June 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/06/) (1)
May 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/05/) (2)
April 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/04/) (1)
March 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/03/) (4)
February 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/02/) (1)
January 2016 (https://blogs.msdn.microsoft.com/martinkearn/2016/01/) (1)
All of 2017 (https://blogs.msdn.microsoft.com/martinkearn/2017/) (1)
Privacy & Cookies (https://msdn.microsoft.com/dn529288) Terms of Use (https://msdn.microsoft.com/cc300389)

Trademarks (https://www.microsoft.com/en-us/legal/intellectualproperty/Trademarks/EN-US.aspx)
(https://www.microsoft.com)
© 2017 Microsoft

Introduction To REST and PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Introduction To REST and PDF

Hochgeladen von

Copyright:

Verfügbare Formate

9/20/2017 Introduction to REST and .

net Web API – Martin Kearn

Introduction to REST and .net Web API

Martin Kearn (https://social.msdn.microsoft.com/profile/Martin+Kearn) January 5, 2015

API; what and why?

What is .net Web API?

public IEnumerable<string> Get()

public string Get(int id)

Web API is part of ‘One ASP.net’

Serialization and Model Binding

public Product GetProduct(int id)

public HttpResponseMessage Post(Product product)

return new HttpResponseMessage(HttpStatusCode.OK);

Dynamic API Help Pages

Tags api (https://blogs.msdn.microsoft.com/martinkearn/tag/api/) asp.net (https://blogs.msdn.microsoft.com/martinkearn/tag/asp-net/) rest

Prabhakar kumar priyadarshi

Abdul Rauf (http://allinterviewquestions.net)

api (https://blogs.msdn.microsoft.com/martinkearn/tag/api/) Installation (https://blogs.msdn.microsoft.com/martinkearn/tag/installation/)

web development (https://blogs.msdn.microsoft.com/martinkearn/tag/web-development/)

Cognitive Services (https://blogs.msdn.microsoft.com/martinkearn/tag/cognitive-services/)

Machine Learning (https://blogs.msdn.microsoft.com/martinkearn/tag/machine-learning/)

Web API (https://blogs.msdn.microsoft.com/martinkearn/tag/web-api/) rest (https://blogs.msdn.microsoft.com/martinkearn/tag/rest/)

cloud hero challenge (https://blogs.msdn.microsoft.com/martinkearn/tag/cloud-hero-challenge/)

visual studio (https://blogs.msdn.microsoft.com/martinkearn/tag/visual-studio/)

Project Oxford (https://blogs.msdn.microsoft.com/martinkearn/tag/project-oxford/)

Shared Services (https://blogs.msdn.microsoft.com/martinkearn/tag/shared-services/)

Entity Framework (https://blogs.msdn.microsoft.com/martinkearn/tag/entity-framework/)

visual studio 2015 (https://blogs.msdn.microsoft.com/martinkearn/tag/visual-studio-2015/)

Future Decoded (https://blogs.msdn.microsoft.com/martinkearn/tag/future-decoded/)

Document Management (https://blogs.msdn.microsoft.com/martinkearn/tag/document-management/)

Privacy & Cookies (https://msdn.microsoft.com/dn529288) Terms of Use (https://msdn.microsoft.com/cc300389)

Das könnte Ihnen auch gefallen