Web API Design Jump Start

About this course

[Music] you [Music] good morning good afternoon good evening wherever in the world that is that you

happen to be this is the Web API design jumpstart and alongside Jeremy look nice I am Christopher Harrison very happy to have you with us what we’re going to do is introduce ourselves we’ll go ahead

and introduce the course talk about what we’re going to talk about and then we’ll kind of launch on into a little bit of MBA stuff and then into well the actual content but first up to everyone which

go ahead and introduce yourself there sure thing so I’m Jeremy lick medicine for those of you who have followed me on lines that the mystery solved the last name is

likeness it’s Lipnick 50 some people like to call it likeness but it is likeness and I’m a principal architect that eye vision which means I get to do a lot of really exciting things on

projects I’m everywhere from a developer who’s in the trenches working on code to a technical project manager to pre-sales and high-level business solutions so I’ve run the whole gamut and I’ve been

doing this for about 20 years which used to sound kind of cool until I realized that the people in the audience are actually coming up on that age themself yeah so it’s based myself a little bit

I’ve been a focus on enterprise apps for two decades okay and a few detours I did a training business for a while okay technology to leverage training also dabbled in gaming a little bit but I’ve

always come back to line of business and that’s been my passion for like it those two decades I like it perfect welcome and I am Christopher Harrison I’m a longtime MCT and I’m just going to be

really rude here if Jeremy flicks to the next slide then we can actually there we go of my slide right there I’m a longtime MCTS and MCT for about 15 years I focused these days on web development

and office 365 and spend a lot of my time it feels like in in this very seat right here actually got started doing technology back in my father brought home a Victorian – a Commodore 64 oh

yeah I miss this stuff I got into pcs realize you can make a career out of this and well here I am like that now as we mentioned of course at the outset this is going to be Web

API design we’ve got six I think fantastic modules for you what are those modules so we’ve got like I said like you said six modules the first ones just a high-level

introduction to Web API so my goal with people watching this is if you know nothing about it we’re going to get you situated and get you kicked off over if you do know something about it I have

something in store for you in the later module so after we talk about Web API and what’s behind it which includes rest we’re going to go into basic design and look at how you actually intentionally

set up these interfaces with Web API we’ll follow that with configuration one of the things I love about Web API is that there’s a lot of dials and switches that you can use to change that

experience then we’ll move into validation and error handling that’s huge how do we deal with posts that have invalid data etc will move into security how do you secure your web API that’s a

very important big question that I get asked yup exactly and so we’ll show a couple ways of doing that and then we’re going to close it out with advanced web API design and these are features of web

api such as versioning if you have a public-facing web api how do you manage multiple versions of that right make sure that people can actually continue to make those calls even if maybe you’ve

changed something so that way you’re not breaking everything that the the world is calling it’s obviously much more complex than just simply making an update to an API inside of a inside of a

DLL exactly perfect I like it now for those of you that are brand-new to two MVA and obviously just tuning in to this course and maybe wondering kind of what level it is that we’re expecting you to

to be at we are expecting that you have some level of Visual Studio 2013 experience we are expecting that you’re hopefully at least familiar with the concept of web api but even if you’re

not that’s okay that I think the way that Jeremy put it to me earlier this morning which is if you haven’t done in web api that’s okay we’re going to explain the basics of what it is and get

you going and if you have done web api then we’re going to help you take your web api skills to the next level now spinning us back into MBA we actually have over 2.6

million registered users which is sort of a mind-boggling as our number yes a pretty big number you can get 50 MBA points for checking this out you’ll notice the voucher code right down there

and I know a lot of people are going to wind up asking that that voucher code is inside of the FAQ tab as well I would also mention that we do of course have live QA throughout the day it’s only the

two of us that are answering questions and honestly it’s mostly going to be me today that’s that’s answering questions so we are going to do our absolute best to get back to everybody with you know

as quickly as we possibly can I am kind of going back and looking through the questions that I missed and so forth but in any event please do ask I would also mention that one of the

things that’s going to wind up happening with this particular MVA and this is the first time that we’ve done this is we are going to be sort of seating the forum that will be associated with this

at every MBA has a forum and we’ll be seating this one with a handful of the big cool questions that we wind up getting inside the Q&A window so do if you do have you know some kind of cool

things that that you’re wondering about please feel free to ask and eventually those will become part of of the forum as well and with that I think we can actually turn our attention to what Web

API is so Jeremy what is Web API Web API is a lot of things so let me just enter at a high level so in this module we’re going to cover exactly what it looks like within Visual Studio and then step

back and talk about design for that perfect I like and then we’ll drive into rest in hate OAS hey wayya yeah that’s the way I always pronounce it I’m sure it’s just a che te OAS but we’ll talk a

little bit about that okay how that that fits in and then we’ll cover the scaffolding that’s actually inside of your visual studio yep so a very high-level overview of what Web API

means for me a visual studio user is where I’d like to start okay okay and so it’s really an option for web applications when I say that if you’re familiar with

the new templates that came out I believe it was Visual Studio 2013 it might be 2012 but those templates went from all of these different types of web applications that you could start with

to just a web app and then you have several options within it yeah a couple people actually asked about hey you know can we also use this to serve up web pages the answer is absolutely and I

love that dialog box because it really is just simply okay well I also want this check I also want write check and and this is a very big improvement even for people that are doing web forms if

you want web forms just simply put in a check and anyway you go I also really love that host and Azure option – oh yes but that’s that’s a different different course absolutely that’s that’s a

different discussion but what’s really neat – and we’ll get into this a little bit is that change authentication button as well so there’s some options out of the box to do that with authentication

and really in a nutshell if you think about Web API well Web API does is it provides a means to stand up RESTful API through visual studio that’s it here and simple and anyone who has a little bit

of history we talked about how long have been in this industry before it is something like me to admit it again yeah yeah okay I’ll stop visiting that but as they’re familiar with WCF and WPF did

what we called soap which was simple object access protocol right and there was really nothing simple about it and it was even more complicated when you had to turn a soap interface into a

restful interface and there were pieces in place but what I really like is how Microsoft listened to the feedback looked at what we need to do with this um created a technology completely based

on rest perfect and and you are going to define rest that there’s already been a couple questions yeah we are going to dig into what rest is and start to define all of our TAS really is a

three-letter acronym yes freeze TLS we were yeah we will jump into all of that perfect so let me take a step back to and rest is going to drive some of what we talked about but this is a Web API

design course so it’s not just the nuts of both of web api does right yep or web api itself it’s web api design so what does that mean and if you take a look I mean

basically what we’re talking about is there’s an intentional approach to building api’s and what that means is you set out to surface something and then you use this as a tool to make it

happen as opposed to starting from the technology up right everything we do is a problem that we’re looking to solve right and we want to solve it with the technology now I would say this is

almost a must have if you have api’s consumed by third-party services but I’m going to say even if it’s internal customers as well because what we’re doing is really looking at a way to be

standard and so there’s a very common easy-to-understand approach to that API and that’s the goal behind design and then we’re going to dive into all of these topics more deeply when I talk

about attention to details but we’ve got consumption of the API standards with response codes etc security versioning restful etc and what we’ll dive into all of those but that is really in a

nutshell what we mean by Web API design to find rest rest and not just simply sleeping somebody actually yeah the rest is what you me tonight yeah I got quite a CLE no not quite

oh so rest is a good thing I mean you do need rest you do need rest yeah we’re talking about rest earlier today and I got plenty of rest before I came into the

studio I flew in from Atlanta so a little bit of a time zone switch but I feel pretty good today so perfect see cuz the rest exactly because the rest totally because of representational

state transfer and I think it’s cool to know what’s behind the acronym just because you know how impressive is that right you’re hanging out with friends what’s the rest it’s representational

state transfer and you know what’s funny is honestly the only reason that I ever remember what it stands for is because knowing what it stands for I don’t think clarifies anything it does

not it absolutely doesn’t so I’m going to preface this by saying we’re in the pragmatic class for rest so I’m not going to go into the the papers and the history and everything behind it I’m

going to look at it from a very pragmatic perspective of what it means for business I’m going to simplify it a little bit and some rest Pyrrhus may or

may not feel like I’m giving it full coverage but in a nutshell rest is a way of creating client-server communications that’s stateless and that’s important so you’re not tracking state over time and

you’re dealing with it as a resource and we’re used to I think in older software doing something called procedure calls and we had very procedural approach to software and even as software moved to

the web even soap is really a procedure based type protocol mm-hmm rest sort of changes that perspective and looks at resources and a resource is simply something that you can access through a

URI throw it through what you type into the address bar in the browser if you will and then allows you to use what’s built into the HTTP protocol to act on that yep and that’s where we talk about

HTTP methods now I did throw in there the word Indian potency just because it’s always a great word that’s the correct I don’t think that word works and scrabbled uh um really no I don’t

think so yeah you get rid squigglies on it which i think generally speaking means it doesn’t work integrate it you know in event if they let de Zod and scramble so

you know who knows right well you can find it on the web so it means it has to be true to it there you go yeah exactly so so anyone who’s worked with and dipp’d in Indian potency knows that it’s

dealing with side effects and there are some schools of thought around how different rest methods deal with side effects what is Indian potency so it really describes the state of something

and whether an operation is going to be repeatable okay so changing the state or not okay if it’s Indian potent and I read this more than I pronounce it so that’s the

correct then what you’re saying is I can do this same operation over and over and I’m not going to see a different result each time so typically for example when you get something from a rest endpoint

you expect it to be the same unless someone came in and modified it behind the scenes perfectly so that’s an example and I will say it’s a style and not a standard so it’s a way of doing

things it’s not a hardcore you must look up and and see 1.2.3 says do it exactly this way yep and the next thing I’m going to step into is something that more

formalizes if you will how rest is and that’s this hae e OAS eight OAS eight o AR so that’s a natural segue into hypermedia as the engine of application state okay

sure and so this is really what I would say rest embodied what it’s saying is hyper media is the key so everything we’re going to do is going to be described by

the way we interface with these restful endpoints so in essence we should be able to operate on resources understand what operations are available and make modifications and do everything we need

to just through the combination of a resource URL and that verb that we act on it so one key with h ato as8 OAS if you will is that typically you return information about what you can do with

datasets so if I go out to a high-level data set I’m not just getting information back I’m also getting location information and operation information so I know that this is where

I go to find a subset of data this is what I can do here’s how I edit the cetera so it’s really just put some more formality around the ways that you can expose restful endpoints okay I got you

and with that I’m going to hop into a demo demos okay yeah let’s actually see some code let’s let’s sort of see how all this comes together exactly so what we’re going to do is is pop over into

internet explorer and I’m going to use something now we talked a little bit about this earlier too so there’s a a form of rest and there’s an add-on that sits on top of Web API that allows you

to use something called OData and it’s a really straightforward easy way of dealing with data operations and exposes it in a standard way we’re not going to dive into a lot of detail here but I

love this site because it exposes some API is that we can go through for our demo so I’m going to do is click through – Oh data services and I’m going to go with the v3 because I’m more familiar

with that hmm and go into this endpoint so what I’ve done right here is I’ve called a rest endpoint okay and you’re now getting the the results from that from that rest endpoint exactly so all

the results have come back and basically that in points the high-level endpoint four set of collections and those collections here are products product details categories but what you’ll see

if you look at this is that for example here in this product so I’m just going to highlight that I’ve got an href and so that’s actually giving me information about navigation it’s telling me

relative to the service I can go to a collection of products and so what I can do up here in my URL is on the end of this URL I’m just going to append products I’m going to navigate to that

and now I’ve got a list of actual products that are in the same point now this is something neat and I wanted to show this in Internet Explorer because OData uses the atom format which is the

popular feed format it’s an XML format exactly so when it receives results it knows how to format those because it’s expecting this is commonly used by RSS data feeds and so it formats it this

nice way well if we want to see what actually came back we’ll go into view source and in my notepad it’s not going to look too pretty but we’re going to pop over to visual studio just paste

that into a new XML document yes yep so we’ll go into a new file XML file open and we’ll paste that and then it will have a nice format that we can see what came back so what I want to show is what

we’ve got is a high-level set of information about the collection and then we’re going to set its products yep exactly and then within that we’ll have a list of entries for various products

so within that for example we have this entry let me just highlight that and that has an identifier and you can see this identifier is actually our service endpoint with this product 0 on the end

ok so that’s how I uniquely identify this specific product in this system and that specific syntax saying that product is zero that’s a that’s an O data

convention direct okay absolutely all right a no data’s open data and that’s just a standardized way of making calls to a back-end data store being able to do things like querying

filtering and and and and those types of things absolutely okay let’s say it’s rapid development of these types of M pright yeah because that way it’s consistent

because of course one of the problems is is that you could stand up and on point I could stand up an endpoint Jeremy here could stand up an endpoint and if it’s all very different things makes it very

hard for me to figure out you know how to how to call each one of those and and one of the things that Jeremy had mentioned earlier was WCF and and so and one of the things that WCF made very

easy to expose out was a little thing called a wisdom document or web services description language which was an XML document that sort of described how all the calls were supposed to be coming in

how all the data was going to look going out and while that whistle document was good because it did give me the ability to quickly figure out okay what do I need to do and there was a lot of

automated tools that will allow me to generate the appropriate classes to make those calls the fact of the matter still remained that it was going to be different here and here and here and

here and so now I’m having to create all of these different classes and so the goal with rest and the goal with OData is to have consistency there so that way regardless of where I go if it’s an O

data standard endpoint and I want to get the product with an ID of 42 then I say products and then paren brand 42 or if I want to get the category with the ID of 42 then it’s going to be categories and

then again paren paren 42 now there’s still of course going to be some things to learn that I need to know what collections exist but at least once I figured that part out I now know how to

make all the appropriate calls that’s the goal here right yeah that’s how CLE the goal and it gives you that feature that you’re used to at WCF where you’ve got right-click and add service rest

reference and go down discovers it yep Oh data provides that capability on top of standard rest exactly and it’s also worth noting that in Visual Studio if you’re doing dotnet

that will even create a data context and give you the ability to do linked queries as well so if you’re used to doing entity framework you can actually make those same calls into Oh data and

that will automatically trance trance late your where statement into a filter clause and will automatically translate your order by into a into a sort clause and it will automatically handle your

top and your skip and all of that good stuff exactly well so yeah cool yeah it’s definitely a way for I would say rapid development of data-driven endpoints as well you can stand up

pretty quickly something using OData on top of that exactly yep so I’m going to come back to this single entry in this list of products and look at a few other options so we have these linked here and

this one says edit so right away I’ve discovered that I’m able to edit this product and it gives me a reference of how I would edit the product so it’s telling me to go to this product zero

endpoint and we’ll get into this a little deeper later on but I do want to show an example of that edit and then I can drill down to category supplier product detail etc so there’s some more

interesting items and then we have it’s bread it’s whole-grain bread etc etc so here’s what I’m going to do I’m going to take this entry I’m going to cut that and just replace the whole document so

now I have a single entry for this bread and I’m just going to edit this a little bit and I’m going to call it wonderful bread wonderful bread and this is whole-grain that is awesome bread okay

okay so let’s try that so now I’m going to jump a little bit ahead of myself and use a tool that I will dive into more details for earlier later on but this is a tool for testing rest

endpoints I’m going to show a couple different tools for that and that’s called postman and that’s available in a in a different browser of course called Chrome yes okay hahahaha that’s one way

to put it that’s that’s that’s the way that I’m going to just slide that in there okay so what I’ve done here and let me zoom in a little bit for you is I’ve put

the in point from my internet explorer session and that’s this whole tracking I do data etc and then I put this product zero because in that XML it told me that product zero was the end point I can use

that it and again jumping a little bit ahead but I happen to know if I do a put that’s an update okay for this and we’ll get into those verbs and what put and post and get and delete and all those

mean a little bit later yeah hatch and headers and everything else I’m just going to show this for the sake of showing it I’m going to come into this raw data and I’m going to grab what I

changed paste it in and then if demos are working this morning when we click this send we get an unsupported media type so it wants atom XML and I got this so let’s try to take this oh that’s

right I need to put this as my content type I was telling it what I wanted to get back and we’re going to talk about all of this in a minute but I’m telling it the content type I’m giving it it’s

like on 10 tight and that content type depending on where you are what you’re doing could be something different so for example it could be Jason which is a much cleaner way of being able to send

data back and forth caress and have to be out of it doesn’t have to be XML that’s correct okay so and we’ll get into that that’s content negotiation and that basically

gives us a few ways to both request and receive data and what i’m doing here is it was complaining about my request so I’m just pasting it one more time to make sure we’re looking good

so we’ve got our entry here and I’m probably just missing the XML type on top so when we make these changes real quick wonderful bread and whole grain what I call it awesome bread modeler

yeah that’ll work alright so we’ll take this back and paste that in and now let’s fire off the send okay so what I got was the status 204 no content so what that’s telling me

is things are great it’s just not giving me back my up it’s telling me hey I got it and we’re good so some form of a 200 for this you may not familiar with your HTTP status

codes 200 anything in that range means that it worked that it was successful and then the specific status code from there is going to indicate whether or not something was going to be sent back

and in this case that 204 simply meant hey look we we got it it works it just didn’t send anything back or to sort of spin this into like a method call analogy this is like a void method that

generally speaking when you call a void method especially one that’s going to be saving into a database if it doesn’t reply back if it doesn’t throw an exception then that’s how I know that

this was successful same exact concept here exact same concept okay so I’m going to do one more step and then we’ll conclude this demo because I know I’ve introduced a lot of new concepts that

we’ll need to drill into I’m going back to that products lesson and now what we can see is it successfully updated to wonderful bread whole grain awesome bread I love it and we did that

completely through just starting at that high-level end point in seeing what collections were available driving into items within the collection the collection told me I could edit it so I

just put the content back with my edits and we have a successful update so I love it this whole class is about how can we create that on the server side and make that experience available so

speaking of which yeah I’m going to jump into some scaffolding now okay so this is where visual studio can just do some of that magic for you exactly okay visual studio does a lot and in fact

when I first started working with this I got a little confused because there’s so many options available and that’s why I wanted to take some time and walk through what the different templates

look like so we know what those variations are within visual studio so we’re going to jump straight into a demo I’m going to come back into my visual studio instance here and I’m just going

to create a new project when we create a new project this is something I mentioned earlier and I’ll zoom in a little bit just so we’ve got this project that’s just simply a web

application hm and then that is going to drill into additional templates that we have so I’m not where about the name or anything I’m just showing an example so I’m going to click

OK and then this is something we saw earlier where we have different templates available and I’m going to show you how to use a template that provides a lot of infrastructure that

you can scale back from and then I’m also going to show you how to use a template that puts all of the references in place but allows you to build from the bottom up so we’ll see what that

different looks like difference looks like so the first thing I’m going to do is pick MVC not Web API yep but down here I’m going to include the references for Web API so I’m just going to tick

that check box I’m going to leave off n ocation the same way nothing special there and click OK and while that’s doing its thing in the background it’s worth highlighting you could have gone

with empty and disability’ drive API or again because I talked to a lot of people who are still doing web forms development that if you’re going to do web forms you can still tack Web API on

to that as well just put the little check box of that screen right listen bol yeah I love where the templates is gone yeah far more flexible so what I’m going to

do within this application is just open it up and show that there’s some controllers and content what you’re not going to find anywhere is we will see that there is a Web API config and this

is the way of notifying the application that web api is going to participate however there are no endpoints so the application just sets up the groundwork for it and it’s a fully functional MVC

site so if I run this it’s going to spin around open up and what we’re going to see is that we’ve got structure for learning about asp.net we can register we can log in so there’s some security

scaffolding etc but right now we just don’t have any web API endpoints so we’ll talk about adding those in a second so let me go into another type for you and show you another example of

how we can scaffold this so I’m going back into project I’m picking web project again mm-hmm only this time I’m going to start with the Web API template okay now one thing you’ll notice is

India is grayed out what’s up with that so when you use the web API template it’s going to scaffold some example web api for you and that includes documentation and i’m going to

show you how that works in a second but it needs MVC to show the documentation for the web api okay so we’re just going to click OK with the defaults here let it spin up now what’s interesting and

and can be conducted up for this is that if I launch this an Internet Explorer I’m just going to let it build and run and it’ll wait for the local host and everything up basically I’ve got a very

simple MVC scaffold I don’t have registration I don’t have login I just have this home page and then I have an API however when I click on the API it’s giving me documentation for registering

and logging in so when we cover security I’m going to talk about how to use these api’s with web api to build your own security ok perfect so that way I can make sure before people start coming in

and saying hey I want to create a brand-new item that I determine whether or not they’re actually allowed to create a brand-new item correct excellent ok and then what we’ve got

here so there’s a count set of API s and then there’s a values and values is is neat in the scaffolding because it really just is some hard-coded values but you can see here I’ve got to get of

API value so let me just go up to my url and I’m going to change that to API values and what you’ll see is authorization has been denied for this request so this demo ends here we have

no authentication and we talked about later but I will dive into to how that works and we’re going to see something a little different in the third template that I show you but if we open up the

source code you’ll see there’s a values controller and it’s just hard coded values but it’s got this authorized attribute and we’ll talk about that in the security module if I were to take

that off I’d be able to show you but we’re going to cover that a little bit later ok one thing I would like to point out with that little screen right there is in the little classic example that

gives you it’s you know returning back strings but there’s really nothing special about the internal code so if you have your own custom objects as long as they are

serializable as long as dotnet as a way to convert them into JSON which it will handle by default that you actually don’t have to do anything special to the object that it will now just

automatically do that if you do want to control over you can do things like data contract and data member and and so forth to control that but at the end of the day it’s still just basic code so if

you’re wanting to save that back into the database it’s very easy to go in and do that so if you’re using let’s say Emily Framework if you’re using your own custom repository it’s very easy to

incorporate that into that code and for people who are listening who have done MVC if you took a look at that you would also notice it looks an awful lot like an MVC controller and there’s a reason

for that that while technically the code base underneath is different that change is actually going forward into asp.net five well the code base underneath that makes the magic happen is different it

behaves the exact same way so those skills and routing and so forth that you learn in an MVC do apply forward into into Web API yeah that’s what’s really nice actually in the old MVC version we

had different types of JSON results etc they did a similar thing this expands that gives it more intention behind the actual concept of building an API and then gives us a pipeline for doing

things so you mentioned serialization we’re going to talk about what happens if you have a complex object that doesn’t serialize and how can we manage that so we’ll cover those pieces later

on when we’re talking about the design so what I want to do is jump into this project creation and I’m going to show you the third option for creating project with Web API so the two I just

showed you for what I call the pull back options you start with a bunch of scaffolding in place and then you sort of pull back into your application and show some of the features you want

specifically but you’ve got great examples and if you’re using that type of authentication and login it’s already there for you so it’s a very nice starting point sometimes though you know

you’re going to build everything from the ground up so you just want the base foundation so that’s what we’re going to create we’ll go back into create a web project and then when we

click okay we’re going to use the empty template and empty does not attempt to generate any type of pages liberating it means empty yep though what’s nice about empty is if

I’m a web forms developer I can click web forms and I can click Web API and I can have those two features added within it I mean we could get really silly and add

mvc2 and have a lot of fun with that what I’m going to do is just leave these off and add Web API by itself so I’m going to click OK there and you notice there’s no authentication because I

didn’t create any scaffolding for that it’s empty so I have to add authentication in myself so I’m going to click OK here let it spin up through the template and what I get is exactly what

was promised a very empty template it has enough to register my routes which is we’ll get into that in a little bit but it’s how we know how to get from a browser request to the actual controller

but my controllers and my models are empty so what I would need to do here is add a controller and I’ll just say a Web API – controller that’s empty let’s go ahead and add that and I’m going to call

it values controller and what that will do is give me a controller that inherits from API controller and then we’re just going to do a public let’s say I H CDP action result I wonder what that is

mmm-hmm and I’m going to return ok new a and B ok so that’s very simple now we’ll get into the explanation of what this is in a minute is that how I kept there we go new empty array of a and B so let me

click play here chugga-chugga-chugga and then we go API values and by default at issues they get and we get they and B voila magic magical did our first web a tie and and if you if we kick back to

Internet Explorer there real quick you’ll notice that that actually just came back in Jason yes okay perfect I like it so here’s what we did is we took kind of a real quick lap

around Web API took a little bit of a look at how things work inside a visual studio and now in the next module we actually want to start digging in and start creating some Web API applications

but what do you say we go ahead we take ten minutes and then we’ll come on back and we’ll keep digging into a Web API we’ll see you then sounds great

[Music]