Skip to content

Latest commit

 

History

History

WebApi

README.md

Web API

A stripped-down version of Visual Studio's out-of-the-box Web API 2.x project template to provide bare-bones support for, in particular, ASP.NET Identity web services (e.g., /API/Account/Register/). Does not include any of the MVC, Web API Help, or other web-based devependencies that ship with the out-of-the-box template. Additionally includes an OData controller for exposing other elements from the Model project, including User, Post, and Comment end points.

OData

Note: The followings provides a high-level overview of the out-of-the-box capabilities of OData as they apply to the WebApi project. For more in-depth coverage of OData, visit odata.org.

Endpoints

The following endpoints are exposed by the OData implementation:

  • /OData/Users
  • /OData/Posts
  • /OData/Comments

Querying Collections

Each OData endpoint supports standard OData parameters via the Query String, including:

  • ?$filter= (e.g., contains(Comments/Body, '@Jeremy'))
  • ?$orderby= (e.g., DateCreated desc)
  • ?$top= and $skip= for paging
  • ?$expand= (e.g., Comments/Likes)
  • ?$select=(e.g., Title,Body,DateCreated)

Retrieving Records

Individual records can be retrieved from an OData collection using the ('PrimaryKey') format. For instance:

  • /Odata/Users('d0457c7c-798c-4a60-b4bd-030bcad7062b')
  • /Odata/Posts(5)
  • /OData/Comments(10)

Note: The Web API OData implementation does not support selecting individual records from entity relationships. For instance, /Odata/Posts(5)/Comments is allowed, but /Odata/Posts(5)/Comments(1) will return an error. Instead, this would need to be retrieved using /Odata/Comments(1).

Web API

Note: The following is simply intended to provide a quick overview of the out-of-the-box endpoints associated with the Web API 2.x project. There are many available resources that provide more thorough investigation of these endpoints elsewhere on the internet.

Endpoints

The following endpoints are defined by the out-of-the-box Web API 2.x project template:

  • /API/Account/UserInfo*
  • /API/Account/Logout [POST]
  • /API/Account/ManageInfo?returnUrl={returnUrl}&generateState={generateState}
  • /API/Account/ChangePassword [POST]
  • /API/Account/SetPassword [POST]
  • /API/Account/AddExternalLogin [POST]
  • /API/Account/RemoveLogin [POST]
  • /API/Account/ExternalLogin?provider={provider}&error={error}
  • /API/Account/ExternalLogins?returnUrl={returnUrl}&generateState={generateState}
  • /API/Account/Register [POST]
  • /API/Account/RegisterExternal* [POST]

* Requires Authentication: The UserInfo and RegisterExternal endpoints require bearer authentication. The bearer token can be retrieved either from the /Token endpoint, or from the /API/Account/ExternalLogin endpoint (as returned via the #access_token). In turn, the bearer token should be prefixed with bearer and relayed via the Authorization HTTP header.

Payloads

The following provide examples of the data expected by each POST endpoint.

ChangePassword

{
  "OldPassword": "OldPassword",
  "NewPassword": "NewPassword",
  "ConfirmPassword": "NewPassword"
}

SetPassword

{
  "NewPassword": "NewPassword",
  "ConfirmPassword": "NewPassword"
}

AddExternalLogin

{
  "ExternalAccessToken": "sample string 1"
}

RemoveLogin

{
  "LoginProvider": "Facebook",
  "ProviderKey": "10152759761386507"
}

Register

{
  "Email": "[email protected]",
  "Password": "Password",
  "ConfirmPassword": "Password"
}

RegisterExternal

{
  "Email": "[email protected]"
}

Changes

While the Web API seeks to maintain parity with the out-of-the-box Web API project template, a number of changes have been made to the templates. These include:

  • All files have been reformated and commented, including the use of XmlDocs.
  • Files have been broken down to one file per class; notably, this affects the /Models directory.
  • Entity Framework dependencies have been moved to the Model project for integration with the data model.
  • Web API OData controllers have been added for Comments and Posts based on the Model project.
  • Added username to the hash generated by the /API/Account/RegisterExternal end point via the ApplicationOAuthProvider.cs class as a convenience.

Important: In the Startup.Auth.cs file, this template overrides the FacebookAuthenticationProvider class's OnAuthenticated property in order to set the DefaultNameClaimType to Email instead of Username, and also adds the email property to the FacebookAuthenticationOptions.Scope collection. This allows the Web API's external token for Facebook to be used with the Web API's //API/Account/RegisterExternal endpoint (which expects an email address for the username), and //API/Account/UserInfo (which expects that the token's username claim will match that same email address).

Removed Files

The out-of-the-box Web API template includes a number of dependencies in order to support Web API Help pages. While Web API Help pages are useful, they a) necessitate a much larger footprint for the project, and b) are only compatible with the basic Web API controller (not the Web API OData controller). For these reasons, the following have been removed from the out-of-the-box template:

/App_Start
  /BundleConfig.cs
  /FilterConfig.cs
  /RouteConfig.cs
/Areas
  /HelpPages
/Content
/Controllers
  /ValuesController.cs
/Fonts
/Scripts
/Views
/favicon.ico
/Project_Readme.html