diff --git a/.gitignore b/.gitignore index da1c6032..b8437ffb 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,5 @@ _[Ss]cripts *.pdb *.mdf *.ldf -.vs \ No newline at end of file +.vs +site \ No newline at end of file diff --git a/docs/clients/dot-net.md b/docs/clients/dot-net.md new file mode 100644 index 00000000..84c3a7de --- /dev/null +++ b/docs/clients/dot-net.md @@ -0,0 +1 @@ + [THIS IS A PLACEHOLDER FOR FUTURE CONTENT] \ No newline at end of file diff --git a/docs/contribution-guidelines.md b/docs/contribution-guidelines.md new file mode 100644 index 00000000..634f4058 --- /dev/null +++ b/docs/contribution-guidelines.md @@ -0,0 +1,73 @@ +# How Can I Contribute? +There are many ways for you to contribute to RESTier. The easiest way is to participate in discussion of +features and issues. You can also contribute by sending pull requests of features or bug fixes to us. +Contribution to the [documentations](http://odata.github.io/RESTier/) is also highly welcomed. + +## Discussion +You can participate into discussions and ask questions about RESTier at our +[Github issues](https://github.com/OData/RESTier/issues). + +## Bug Reports +When reporting a bug at the issue tracker, fill the template of issue. The issue related to other libraries +should not be reported in RESTier library issue tracker, but be reported to other libraries' issue tracker. + +## Pull Requests +**Pull request is the only way we accept code and document contribution.** Pull request of document, features +and bug fixes are both welcomed. Refer to this [link](https://help.github.com/articles/using-pull-requests/) +to learn details about pull request. Before you send a pull request to us, you need to make sure you've +followed the steps listed below. + +### Pick an issue to work on +You should either create or pick an issue on the [issue tracker](https://github.com/OData/RESTier/issues) +before you work on the pull request. After the RESTier team has reviewed this issue and change its label +to "accepting pull request", you can work on the code change. + +### Prepare Tools +[Atom](https://atom.io/) with package [atom-beautify](https://atom.io/packages/atom-beautify) and +[markdown-toc](https://atom.io/packages/markdown-toc) is recommended to edit the document. +[MarkdownPad](http://www.markdownpad.com/) can also be used to edit the document.
+Visual Studio 2015 is recommended for code contribution. + +### Steps to create a pull request +These are the recommended steps to create a pull request:
+ +1. Create a forked repository of [https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git) +2. Clone the forked repository into your local environment +3. Add a git remote to upstream for local repository with command _git remote add upstream +[https://github.com/OData/RESTier.git](https://github.com/OData/RESTier.git)_ +4. Make code changes and add test cases, refer Test specification section for more details about test +5. Test the changed codes with one-click build and test script +6. Commit changed code to local repository with clear message +7. Rebase the code to upstream via command _git pull --rebase upstream master_ and resolve conflicts +if there is any then continue rebase via command _git pull --rebase continue_ +8. Push local commit to the forked repository +9. Create pull request from forked repository Web console via comparing with upstream. +10. Complete a Contributor License Agreement (CLA), refer below section for more details. +11. Pull request will be reviewed by Microsoft OData team +12. Address comments and revise code if necessary +13. Commit the changes to local repository or amend existing commit via command _git commit --amend_ +14. Rebase the code with upstream again via command _git pull --rebase upstream master_ and resolve +conflicts if there is any then continue rebase via command _git pull --rebase continue_ +15. Test the changed codes with one-click build and test script again +16. Push changes to the forked repository and use _--force_ option if existing commit is amended +17. Microsoft OData team will merge the pull request into upstream + +### Test specification +All tests need to be written with xUnit. Here are some rules to follow when you are organizing the +test code: + +- **Project name correspondence** (`X -> X.Tests`). For instance, all the test code of the `Microsoft.Restier.Core` project should be placed in the `Microsoft.Restier.Core.Tests` project. Path and file name correspondence. (`X/Y/Z/A.cs -> X.Tests/Y/Z/ATests.cs`). For example, the test code of the `ConventionBasedApiModelBuilder` class (in the `Microsoft.Restier.Core/Convention/ConventionBasedApiModelBuilder.cs` file) should be placed in the `Microsoft.Restier.Core.Tests/Convention/ConventionBasedApiModelBuilderTests.cs` file. +- **Namespace correspondence** (`X.Tests/Y/Z -> X.Tests.Y.Z`). The namespace of the file should strictly follow the path. For example, the namespace of the `ConventionBasedApiModelBuilderTests.cs` file should be `Microsoft.Restier.Core.Tests.Convention`. +- **Utility classes**. The file for a utility class can be placed at the same level of its user or a shared level that is visible to all its users. But the file name must **NOT** be ended with `Tests` to avoid any confusion. +- **Integration and scenario tests**. Those tests usually involve multiple modules and have some specific scenarios. They should be placed separately in `X.Tests/IntegrationTests` and `X.Tests/ScenarioTests`. There is no hard requirement of the folder structure for those tests. But they should be organized logically and systematically as possible. + +### Complete a Contribution License Agreement (CLA) +You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies +that you are granting us permission to use the submitted change according to the terms of the +project's license, and that the work being submitted is under appropriate copyright. + +Please submit a Contributor License Agreement (CLA) before submitting a pull request. +[Download the agreement](https://github.com/odata/odatacpp/wiki/files/Microsoft Contribution License Agreement.pdf)), +sign, scan, and email it back to [cla@microsoft.com](mailto:cla@microsoft.com). Be sure to include your Github +user name along with the agreement. Only after we have received the signed CLA, we'll review the pull request that +you send. You only need to do this once for contributing to any Microsoft open source projects. \ No newline at end of file diff --git a/docs/extending-restier/additional-operations.md b/docs/extending-restier/additional-operations.md new file mode 100644 index 00000000..413f74da --- /dev/null +++ b/docs/extending-restier/additional-operations.md @@ -0,0 +1,69 @@ +## Additional WebAPI Operations + +RESTier is built on top of ASP.NET Web API, so like our regular OData support, augmenting your service +with additional actions is very simple. + +First, you must add the action to the EDM Model Builder. + +Currently RESTier can not route an operation request to a method defined in API class for operation model +building, user need to define its own controller with ODataRoute attribute for operation route. + +Operation includes function (bounded), function import (unbounded), action (bounded), and action(unbounded). + +For function and action, the ODataRoute attribute must include namespace information. There is a way to simplify +the URL to omit the namespace, user can enable this via call "config.EnableUnqualifiedNameCall(true);" during registering. + +For function import and action import, the ODataRoute attribute must NOT include namespace information. + +RESTier also supports operation request in batch request, as long as user defines its own controller for operation route. + +This is an example on how to define customized controller with ODataRoute attribute for operation. + +```cs +using System; +using System.Collections.Generic; +using System.Linq; +using System.Net; +using System.Web.Http; +using System.Web.OData; +using System.Web.OData.Extensions; +using System.Web.OData.Routing; +using Microsoft.OData.Edm.Library; +using Microsoft.OData.Service.Sample.Trippin.Api; +using Microsoft.OData.Service.Sample.Trippin.Models; + +namespace Microsoft.OData.Service.Sample.Trippin.Controllers +{ + public class TrippinController : ODataController + { + private TrippinApi Api + { + get + { + if (api == null) + { + api = new TrippinApi(); + } + + return api; + } + } + ... + // Unbounded action does not need namespace in route attribute + [ODataRoute("ResetDataSource")] + public IHttpActionResult ResetDataSource() + { + // reset the data source; + return StatusCode(HttpStatusCode.NoContent); + } + + [ODataRoute("Trips({key})/Microsoft.OData.Service.Sample.Trippin.Models.EndTrip")] + public IHttpActionResult EndTrip(int key) + { + var trip = DbContext.Trips.SingleOrDefault(t => t.TripId == key); + return Ok(Api.EndTrip(trip)); + } + ... + } +} +``` \ No newline at end of file diff --git a/docs/extending-restier/in-memory-provider.md b/docs/extending-restier/in-memory-provider.md new file mode 100644 index 00000000..2d8347fe --- /dev/null +++ b/docs/extending-restier/in-memory-provider.md @@ -0,0 +1,84 @@ +## In-Memory Data Provider + +RESTier supports building an OData service with **all-in-memory** resources. However currently RESTier +has not provided a dedicated in-memory provider module so users have to write some service code to bootstrap +the initial model with EDM types themselves. There is a sample service with in-memory provider [here](https://github.com/OData/RESTier/tree/apidev/test/ODataEndToEndTests/Microsoft.OData.Service.Sample.TrippinInMemory). +This subsection mainly talks about how such a service is created. + +First please create an **Empty ASP.NET Web API** project following the instructions in [Section 1.2](http://odata.github.io/RESTier/#01-02-Bootstrap). Stop **BEFORE** the **Generate the model classes** part. + +### Create the Api class +Create a simple data type `Person` with some properties and "fabricate" some fake data. Then add the first entity set `People` to the `Api` class: + + using System.Collections.Generic; + using System.Collections.ObjectModel; + using System.Linq; + using System.Threading; + using System.Threading.Tasks; + using System.Web.OData.Builder; + using Microsoft.OData.Edm; + using Microsoft.Restier.Core; + using Microsoft.Restier.Core.Model; + + namespace Microsoft.OData.Service.Sample.TrippinInMemory + { + public class TrippinApi : ApiBase + { + private static readonly List people = new List + { + ... + }; + + public IQueryable People + { + get { return people.AsQueryable(); } + } + } + } + +### Create an initial model +Since the RESTier convention will not produce any EDM type, an initial model with at least the `Person` type needs to be created by service. Here the `ODataConventionModelBuilder` from OData Web API is used for quick model building. +Any model building methods supported by Web API OData can be used here, refer to **[Web API OData Model builder ](http://odata.github.io/WebApi/#02-01-model-builder-abstract)**document for more information. + + namespace Microsoft.OData.Service.Sample.TrippinInMemory + { + public class TrippinApi : ApiBase + { + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + services.AddService(new ModelBuilder()); + return base.ConfigureApi(services); + } + + private class ModelBuilder : IModelBuilder + { + public Task GetModelAsync(InvocationContext context, CancellationToken cancellationToken) + { + var builder = new ODataConventionModelBuilder(); + builder.EntityType(); + return Task.FromResult(builder.GetEdmModel()); + } + } + } + } + +### Configure the OData endpoint +Replace the `WebApiConfig` class with the following code. No need to create a custom controller if users don't have attribute routing. + + using System.Web.Http; + using Microsoft.Restier.Publisher.OData.Batch; + + namespace Microsoft.OData.Service.Sample.TrippinInMemory + { + public static class WebApiConfig + { + public static void Register(HttpConfiguration config) + { + config.MapRestierRoute( + "TrippinApi", + "api/Trippin", + new RestierBatchHandler(GlobalConfiguration.DefaultServer)).Wait(); + } + } + } + diff --git a/docs/extending-restier/temporal-types.md b/docs/extending-restier/temporal-types.md new file mode 100644 index 00000000..f268a39a --- /dev/null +++ b/docs/extending-restier/temporal-types.md @@ -0,0 +1,77 @@ +# Temporal Types + +When using the Microsoft.Restier.Providers.EntityFramework provider, temporal types are now supported. The table below +shows how Temporal Types map to SQL Types: + +| EF Type | SQL Type | Edm Type | Need ColumnAttribute? | +|:---------------------:|:------------------:|:------------------:|:---------------------:| +| System.DateTime | DateTime/DateTime2 | Edm.DateTimeOffset | Y | +| System.DateTimeOffset | DateTimeOffset | Edm.DateTimeOffset | N | +| System.DateTime | Date | Edm.Date | Y | +| System.TimeSpan | Time | Edm.TimeOfDay | Y | +| System.TimeSpan | Time | Edm.Duration | N | + +The next sections illustrate how to use use temporal types in various scenarios. + +## Edm.DateTimeOffset +Suppose you have an entity class `Person`, all the following code define `Edm.DateTimeOffset` properties in the +EDM model though the underlying SQL types are different (see the value of the `TypeName` property). You can see +Column attribute is optional here. + + + using System; + using System.ComponentModel.DataAnnotations.Schema; + + public class Person + { + public DateTime BirthDateTime1 { get; set; } + + [Column(TypeName = "DateTime")] + public DateTime BirthDateTime2 { get; set; } + + [Column(TypeName = "DateTime2")] + public DateTime BirthDateTime3 { get; set; } + + public DateTimeOffset BirthDateTime4 { get; set; } + } + + +## Edm.Date +The following code define an `Edm.Date` property in the EDM model. + + using System; + using System.ComponentModel.DataAnnotations.Schema; + + public class Person + { + [Column(TypeName = "Date")] + public DateTime BirthDate { get; set; } + } + +## Edm.Duration +The following code define an `Edm.Duration` property in the EDM model. + + using System; + using System.ComponentModel.DataAnnotations.Schema; + + public class Person + { + public TimeSpan WorkingHours { get; set; } + } + +## Edm.TimeOfDay +The following code define an `Edm.TimeOfDay` property in the EDM model. Please note that you MUST NOT omit the +`ColumnTypeAttribute` on a `TimeSpan` property otherwise it will be recognized as an `Edm.Duration` as described above. + + using System; + using System.ComponentModel.DataAnnotations.Schema; + + public class Person + { + [Column(TypeName = "Time")] + public TimeSpan BirthTime { get; set; } + } + +As before, if you have the need to override `ODataPayloadValueConverter`, please now change to override +`RestierPayloadValueConverter` instead in order not to break the payload value conversion specialized for these +temporal types. \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..da37213a --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,17 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](http://mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs help` - Print this help message. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..8b7614c6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,48 @@ +# Welcome to RESTier! + +RESTier is a RESTful API development framework for building standardized, OData V4 based RESTful services on .NET +platform. It can be seen as a middle-ware on top of [**Web API OData**](http://odata.github.io/WebApi/). + +RESTier is the spiritual successor to [WCF Data Services](https://en.wikipedia.org/wiki/WCF_Data_Services). Instead of +generating endless boilerplate code with the current Web API + OData toolchain, RESTier helps you boostrap a standardized, +queryable HTTP-based REST interface in literally minutes. And that's just the beginning. + +Like WCF Data Services before it, RESTier provides simple and straightforward ways to shape queries and intercept submissions +before and after they hit the database. And like Web API + OData, you still have the flexibility to add your own +custom queries and actions with techniques you're already familiar with. + +But RESTier isn't just for OData and the Entity Framework. It also supports adding additional publishers to support other +protocols and additional providers to support other data sources. + +## What is OData? + +OData stands for the Open Data Protocol. OData enables the creation and consumption of RESTful APIs, which allow +resources, defined in a data model and identified by using URLs, to be published and edited by Web clients using +simple HTTP requests. + +OData was originally designed by Microsoft to be a framework for exposing Entity Framework objects over REST services. +The first concepts shipped as "Project Astoria" in 2007. By 2009, the concept had evolved enough for Microsoft to +announce OData, along with a [larger effort](https://blogs.msdn.microsoft.com/odatateam/2009/11/17/breaking-down-data-silos-the-open-data-protocol-odata/) +to push the format as an insustry standard. + +Work on the current version of the protocol (V4) began in April 2012, and was ratified by OASIS as an industry standard in Feb 2014. + +You can find out more about OData at [OData.org](http://www.odata.org/). + +## RESTier Contributors + +Special thanks to everyone involved in making RESTier the best API development platform for .NET. The following people +have made various contributions to the codebase: + +| Microsoft | External | +|---------------|----------------| +| Lewis Cheng | Cengiz Ilerler | +| Challenh | Kemal M | +| Eric Erhardt | Robert McLaws | +| Vincent He | | +| Dong Liu | | +| Layla Liu | | +| Fan Ouyang | | +| Congyong S | | +| Mark Stafford | | +| Ray Yao | | \ No newline at end of file diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..c629fb2b --- /dev/null +++ b/docs/license.md @@ -0,0 +1 @@ +[THIS IS A PLACEHOLDER FOR FUTURE CONTENT] \ No newline at end of file diff --git a/docs/release-notes/0-3-0-beta1.md b/docs/release-notes/0-3-0-beta1.md new file mode 100644 index 00000000..14512b6c --- /dev/null +++ b/docs/release-notes/0-3-0-beta1.md @@ -0,0 +1,20 @@ +## Downloads + + - NuGet: `Install-Package Microsoft.Restier -Version 0.3.0-beta1 -Pre` [[Website](http://www.nuget.org/packages/Microsoft.Restier/0.3.0-beta1)] + - Source: [[Zip](https://github.com/OData/RESTier/archive/0.3.0-beta1.zip)] [[Tarball](https://github.com/OData/RESTier/archive/0.3.0-beta1.tar.gz)] + +## New Features + + - Complex type support [#96](https://github.com/OData/RESTier/issues/96) + +## Enhancements + + - Northwind service uses script to generate database instead of .mdf/.ldf files. [#77](https://github.com/OData/RESTier/issues/77) + - Add StyleCop and FxCop to build process to ensure code quality. + - TripPin service supports singleton. + - Visual Studio 2015 and MSSQLLocalDB. + - Use xUnit 2.0 as the test framework for RESTier. [#104](https://github.com/OData/RESTier/issues/104) + +## Bug Fixes + + - None in this release. \ No newline at end of file diff --git a/docs/release-notes/0-3-0-beta2.md b/docs/release-notes/0-3-0-beta2.md new file mode 100644 index 00000000..96fc3139 --- /dev/null +++ b/docs/release-notes/0-3-0-beta2.md @@ -0,0 +1,19 @@ +## Downloads + + - NuGet: `Install-Package Microsoft.Restier -Version 0.3.0-beta2 -Pre` [[Website](http://www.nuget.org/packages/Microsoft.Restier/0.3.0-beta2)] + - Source: [[Zip](https://github.com/OData/RESTier/archive/0.3.0-beta2.zip)] [[Tarball](https://github.com/OData/RESTier/archive/0.3.0-beta2.tar.gz)] + +## New Features + + - [[Issue](https://github.com/OData/RESTier/issues/126)] [[PR](https://github.com/OData/RESTier/pull/159)] Support concrete classes that implement IDbSet>T< by [mkemal](https://github.com/mkemal) + - [[Issue](https://github.com/OData/RESTier/issues/138)] [[PR](https://github.com/OData/RESTier/pull/194)] Support Edm.Date [Tutorial](http://odata.github.io/RESTier/#03-04-Date) + +## Enhancements + + - Automatically start TripPin service when running E2E cases [#146](https://github.com/OData/RESTier/issues/146) + - No need to change machine configuration for running tests under Release mode + +## Bug Fixes + + - Fix incorrect status code [#115](https://github.com/OData/RESTier/issues/115) + - Computed annotation should not be added for Identity property [#116](https://github.com/OData/RESTier/issues/116) \ No newline at end of file diff --git a/docs/release-notes/0-4-0-rc.md b/docs/release-notes/0-4-0-rc.md new file mode 100644 index 00000000..1f7afaa1 --- /dev/null +++ b/docs/release-notes/0-4-0-rc.md @@ -0,0 +1,26 @@ +## Downloads + + - NuGet: `Install-Package Microsoft.Restier -Version 0.4.0-rc -Pre` [[Website](http://www.nuget.org/packages/Microsoft.Restier/0.4.0-rc)] + - Source: [[Zip](https://github.com/OData/RESTier/archive/0.4.0-rc.zip)] [[Tarball](https://github.com/OData/RESTier/archive/0.4.0-rc.tar.gz)] + +## New Features + + - Unified hook handler mechanism for users to inject hooks, [Tutorial](http://odata.github.io/RESTier/#04-04-Hook-Handler) + - Built-in `RestierController` now handles most CRUD scenarios for users including entity set access, singleton access, entity access, property access with $count/$value, $count query option support. [#136](https://github.com/OData/RESTier/issues/136), [#193](https://github.com/OData/RESTier/issues/193), [#234](https://github.com/OData/RESTier/issues/234), [Tutorial](http://odata.github.io/RESTier/#03-05-Controllers) + - Support building entity set, singleton and operation from `Api` (previously `Domain`). Support navigation property binding. Now users can save much time writing code to build model. [#207](https://github.com/OData/RESTier/issues/207), [Tutorial](http://odata.github.io/RESTier/#02-06-Model-building) + - Support in-memory data source provider [#189](https://github.com/OData/RESTier/issues/189) + +## Enhancements + + - Thorough API cleanup, code refactor and concept reduction [#164](https://github.com/OData/RESTier/issues/164) + - The Conventions project was merged into the Core project. Conventions are now enabled by default. The `OnModelExtending` convention was removed due to inconsistency. [#191](https://github.com/OData/RESTier/issues/191) + - Add a sample service with an in-memory provider [#189](https://github.com/OData/RESTier/issues/189) + - Unified exception-handling process [#24](https://github.com/OData/RESTier/issues/24), [#26](https://github.com/OData/RESTier/issues/26) + - Simplified `MapRestierRoute` now takes an `Api` class instead of a controller class. No custom controller required in simple cases. + - Update project URL in RESTier NuGet packages. + +## Bug Fixes + + - Fix IISExpress instance startup issue in E2E tests [#145](https://github.com/OData/RESTier/issues/145), [#241](https://github.com/OData/RESTier/issues/241) + - Should return 400 if there is any invalid query option [#176](https://github.com/OData/RESTier/issues/176) + - EF7 project bug fixes [#253](https://github.com/OData/RESTier/issues/253), [#254](https://github.com/OData/RESTier/issues/254) \ No newline at end of file diff --git a/docs/release-notes/0-4-0-rc2.md b/docs/release-notes/0-4-0-rc2.md new file mode 100644 index 00000000..212a8ac4 --- /dev/null +++ b/docs/release-notes/0-4-0-rc2.md @@ -0,0 +1,8 @@ +## Downloads + + - NuGet: `Install-Package Microsoft.Restier -Version 0.4.0-rc2 -Pre` [[Website](http://www.nuget.org/packages/Microsoft.Restier/0.4.0-rc2)] + - Source: [[Zip](https://github.com/OData/RESTier/archive/0.4.0-rc2.zip)] [[Tarball](https://github.com/OData/RESTier/archive/0.4.0-rc2.tar.gz)] + +## Bug Fixes + + - Support string as return type or argument of functions [#258](https://github.com/OData/RESTier/issues/258) \ No newline at end of file diff --git a/docs/release-notes/0-5-0-beta.md b/docs/release-notes/0-5-0-beta.md new file mode 100644 index 00000000..c3257ad1 --- /dev/null +++ b/docs/release-notes/0-5-0-beta.md @@ -0,0 +1,32 @@ +## Downloads + + - NuGet: `Install-Package Microsoft.Restier -Pre` [[Website](http://www.nuget.org/packages/Microsoft.Restier/0.5.0-beta)] + - Source: [[Zip](https://github.com/OData/RESTier/archive/0.5.0-beta.zip)] [[Tarball](https://github.com/OData/RESTier/archive/0.5.0-beta.tar.gz)] + +## New Features + + - [[Issue](https://github.com/OData/RESTier/issues/150)] [[PR](https://github.com/OData/RESTier/pull/286)] Integrate Microsoft Dependency Injection Framework into RESTier. [Tutorial](http://odata.github.io/RESTier/#04-04-Api-Service). + - [[Issue](https://github.com/OData/RESTier/issues/273)] [[PR](https://github.com/OData/RESTier/pull/278)] Support temporal types in Restier.EF. [Tutorial](http://odata.github.io/RESTier/#03-07-Temporal). + - [[Issue](https://github.com/OData/RESTier/issues/383)] [[PR](https://github.com/OData/RESTier/pull/402)] Adopt Web OData Conversion Model builder as default EF provider model builder. [Tutorial](http://odata.github.io/WebApi/#02-04-convention-model-builder). + - [[Issue](https://github.com/OData/RESTier/issues/360)] [[PR](https://github.com/OData/RESTier/pull/399)] Support $apply in RESTier. [Tutorial](http://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html). + +## Enhancements + + - The concept of **hook handler** now becomes **API service** after DI integration. + - The interface `IHookHandler` and `IDelegateHookHandler` are removed. The implementation of any custom API service (previously known as hook handler) should also change accordingly. But this should not be big change. Please see [Tutorial](http://odata.github.io/RESTier/#04-04-Api-Service) for details. + - `AddHookHandler` is now replaced with `AddService` from DI. Please see [Tutorial](http://odata.github.io/RESTier/#04-04-Api-Service) for details. + - `GetHookHandler` is now replaced with `GetApiService` and `GetService` from DI. Please see [Tutorial](http://odata.github.io/RESTier/#04-04-Api-Service) for details. + - All the serializers and `DefaultRestierSerializerProvider` are now public. But we still need to address [#301](https://github.com/OData/RESTier/issues/301) to allow users to override the serializers. + - The interface `IApi` is now removed. Use `ApiBase` instead. We never expect users to directly implement their API classes from `IApi` anyway. The `Context` property in `IApi` now becomes a public property in `ApiBase`. + - Previously the `ApiData` class is very confusing. Now we have given it a more meaningful name `DataSourceStubs` which accurately describes the usage. Along with this change, we also rename `ApiDataReference` to `DataSourceStubReference` accordingly. + - `ApiBase.ApiConfiguration` is renamed to `ApiBase.Configuration` to keep consistent with `ApiBase.Context`. + - The static `Api` class is now separated into two classes `ApiBaseExtensions` and `ApiContextExtensions` to eliminate the ambiguity regarding the previous `Api` class. +## Bug Fixes + + - [[Issue](https://github.com/OData/RESTier/issues/123)] [[PR](https://github.com/OData/RESTier/pull/294)] Fix a bug that prevents using `Edm.Int64` as entity key. + - [[Issue](https://github.com/OData/RESTier/issues/269)] [[PR](https://github.com/OData/RESTier/pull/271)] Fix a bug that `NullReferenceException` is thrown when POST/PATCH/PUT with null property values. + - [[Issue](https://github.com/OData/RESTier/issues/287)] [[PR](https://github.com/OData/RESTier/pull/314)] Fix a bug that $count does not work correctly when there is $expand. + - [[Issue](https://github.com/OData/RESTier/issues/304)] [[PR](https://github.com/OData/RESTier/pull/306)] Fix a bug that `GetModelAsync` is not thread-safe. + - [[Issue](https://github.com/OData/RESTier/issues/304)] [[PR](https://github.com/OData/RESTier/pull/322)] Fix a bug that if `GetModelAsync` takes too long to complete, any subsequent request will fail. + - [[Issue](https://github.com/OData/RESTier/issues/308)] [[PR](https://github.com/OData/RESTier/pull/313)] Fix a bug that `NullReferenceException` is thrown when `ColumnTypeAttribute` does not have a `TypeName` property specified. + - [[Issue](https://github.com/OData/RESTier/issues/309)][[Issue](https://github.com/OData/RESTier/issues/310)][[Issue](https://github.com/OData/RESTier/issues/311)][[Issue](https://github.com/OData/RESTier/issues/312)] [[PR](https://github.com/OData/RESTier/pull/313)] Fix various bugs in the RESTier query pipeline. \ No newline at end of file diff --git a/docs/server/filters.md b/docs/server/filters.md new file mode 100644 index 00000000..3e2a287c --- /dev/null +++ b/docs/server/filters.md @@ -0,0 +1,64 @@ +# EntitySet Filters + +Have you ever wanted to limit the results of a particular query based on the current user, or maybe you only want +to return results that are marked "active"? + +EntitySet Filters allow you to consistently control the shape of the results returned from particular EntitySets, +even across navigation properties. + +## Convention-Based Filtering + +Like the rest of RESTier, this is accomplished through a simple convention that +meets the following criteria: + + 1. The filter method name must be `OnFilter{EntitySetName}`, where `{EntitySetName}` is the name the target EntitySet. + 2. It must be a `protected internal` method on the implementing `EntityFrameworkApi` class. + 3. It should accept an IQueryable parameter and return an IQueryable result where T is the Entity type. + +### Example + +```cs +using Microsoft.Restier.Core; +using Microsoft.Restier.Provider.EntityFramework; +using System.Data.Entity; +using System.Linq; +using System.Security.Claims; +using System.Threading.Tasks; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Filters queries to the Trips EntitySet to only return Users that have Trips. + /// + protected internal IQueryable OnFilterPeople(IQueryable entitySet) + { + return entitySet.Where(c => c.Trips.Any()).AsQueryable(); + } + + /// + /// Filters queries to the Trips EntitySet to only return the current user's Trips. + /// + protected internal IQueryable OnFilterTrips(IQueryable entitySet) + { + return entitySet.Where(c => c.PersonId == ClaimsPrincipal.Current.FindFirst("currentUserId")).AsQueryable(); + } + + } + +} +``` + +## Centralized Filtering + +TODO: Pull content from Section 2.8. \ No newline at end of file diff --git a/docs/server/interceptors.md b/docs/server/interceptors.md new file mode 100644 index 00000000..b738ba9d --- /dev/null +++ b/docs/server/interceptors.md @@ -0,0 +1,301 @@ +# Interceptors + +Interceptors allow you to process validation and business logic before *and after* Entities hit the database. For +example, you may need to validate some external business rules before the object is saved, but then after it's saved, +you may need to dump the object to an Azure Storage Queue to get picked up by a WebJob for further processing out-of-band. + +The way RESTier accomplishes this is virtually identical to the [Method Authorization](/server/method-authorization/) +feature. This means there are once again two different approaches to tackle the task. + +As before, no matter what approach you chose, the concept is simple. Either technique uses a function that returns boolean. +Return `true`, and processing continues normally. Return `false`, and RESTier returns a 403 Unauthorized to the client. + +## Convention-Based Interception +Users can control if one of the four submit operations is allowed on some entity set or action by putting some +`protected internal` methods into the `Api` class. The method name must conform to the convention +`On{{BeforeOperation}/{AfterOperation}}{TargetName}`. + + + + + + + + + + + + +
The possible values for {BeforeOperation} are:The possible values for {AfterOperation} are:The possible values for {TargetName} are:
+
    +
  • Inserting
    • +
  • Updating
    • +
  • Deleting
    • +
  • Executing
    • +
+ 		+
    +
  • Inserted
    • +
  • Updated
    • +
  • Deleted
    • +
  • Executed
    • +
+ 		+
    +
  • EntitySetName
    • +
  • ActionName
    • +
+
+ +### Example + +The example below demonstrates how both types of `{TargetName}` can be used. + +- The first method shows a simple way to prevent *any* user from deleting a particular EntitySet. +- The second method shows how you can integrate role-based security using multiple techniques. +- The third method shows how to prevent execution a custom Action. + +```cs +using Microsoft.Restier.Providers.EntityFramework; +using System; +using System.Security.Claims; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Specifies whether or not a Trip can be deleted from an EntitySet. + /// + protected void OnInsertingTrip(Trip trip) + { + Trace.WriteLine($"{DateTime.Now.ToString()}: {trip.TripId} is being Inserted."); + + if (string.IsNullOrWhiteSpace(trip.Description)) + { + throw new ODataException("The Trip Description cannot be blank."); + } + } + + /// + /// Specifies whether or not a Trip can be deleted from an EntitySet. + /// + protected void OnInsertedTrip(Trip trip) + { + Trace.WriteLine($"{DateTime.Now.ToString()}: {trip.tripId} has been Inserted."); + + // Pseudocode that represents a real business process. + // EmailManager.SendTripWelcome(trip); + } + + } + +} +``` + +## Centralized Interception + +In addition to the more granular convention-based approach, you can also centralize processing into one location. This is +useful if + +User can use interface `IChangeSetItemAuthorizer` to define any customize authorize logic to see whether user is +authorized for the specified submit, if this method return false, then the related query will get error code 403 (Forbidden). + +There are two steps to plug in the centralized authorization logic. + +- Create a class that implements `IChangeSetItemAuthorizer`. +- Register that class with RESTier through Dependency Injection (DI). + +### Example + +```cs +using Microsoft.OData.Core; +using Microsoft.Restier.Providers.EntityFramework; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// + /// + public class CustomAuthorizer : IChangeSetItemAuthorizer + { + + // The inner handler will call CanUpdate/Insert/Delete method + private IChangeSetItemProcessor Inner { get; set; } + + /// + /// + /// + public Task AuthorizeAsync(SubmitContext context, ChangeSetItem item, CancellationToken cancellationToken) + { + // TODO: RWM: Provide legitimate samples here, along with parameter documentation. + } + + } + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Allows us to leverage DI to inject additional capabilities into RESTier. + /// + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + return base.ConfigureApi(services) + .AddService(); + } + + } + +} +``` + +NEEDS CLARIFICATION: +In CustomizedAuthorizer, user can decide whether to call the RESTier logic, if user decide to call the RESTier logic, +user can defined a property like "private IChangeSetItemAuthorizer Inner {get; set;}" in class CustomizedAuthorizer, +then call Inner.Inspect() to call RESTier logic which call Authorize part logic defined in section 2.3. + +## Unit Testing Considerations + +Because both of these methods are de-coupled from the code that interacts with the database, the Authorization +logic is easily testable, without having to fire up the entire Web API + RESTier pipeline. + +### Setting up your Unit Test + +If you don't have a unit test project for your API project already, start by creating one. Repeat the process +outlined in "Getting Started" to install the RESTier packages into your Unit Test project. The add the FluentAssertions +package. + +Next, go back to your API project. Expand the "Properties" node, double-click AssemblyInfo.cs, and add the following line +to the very end of the file: `[assembly: InternalsVisibleTo("{TestProjectAssembly}")]`, making sure you replace +{TestProjectAssembly} with the actual assembly name. This is important, because otherwise the tests won't be able to see +the `protected internal` methods the authorization conventions use. + +### Example + +Given the [Convention-Based Authorization](#convention-based-authorization) example, the tests below should have 100% code +coverage, and should pass without any required changes. + +```cs +using FluentAssertions; +using Microsoft.OData.Core; +using Microsoft.OData.Service.Sample.Trippin.Api; +using Microsoft.Restier.Providers.EntityFramework; +using Microsoft.VisualStudio.TestTools.UnitTesting; +using System; +using System.Security.Claims; + +namespace Trippin.Tests.Api +{ + + /// + /// Test cases for the RESTier Method Authorizers. + /// + [TestClass] + public class TrippinApiTests + { + + #region Trips EntitySet + + /// + /// Tests if the Trips EntitySet is properly configured to reject delete requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanDelete_IsConfigured() + { + var api = new TrippinApi(); + api.CanDeleteTrips.Should().BeFalse(); + } + + /// + /// Tests if the Trips EntitySet is properly configured to accept Admin update requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanUpdate_IsAdmin() + { + var api = new TrippinApi(); + + // We won't be testing HttpContext-related security here, because that requires mocking, + // which is outside the scope of this document. + AuthenticateAsAdmin(); + api.CanUpdateTrips.Should().BeTrue(); + } + + /// + /// Tests if the Trips EntitySet is properly configured to reject non-Admin update requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanUpdate_IsNotAdmin() + { + var api = new TrippinApi(); + // We won't be testing HttpContext-related security here, because that requires mocking, + // which is outside the scope of this document. + AuthenticateAsNonAdmin(); + api.CanUpdateTrips.Should().BeFalse(); + } + + #endregion + + #region Actions + + /// + /// Tests if the Trips EntitySet is properly configured to reject delete requests. + /// + [TestMethod] + public void TrippinApi_CanExecuteResetDataSource_IsConfigured() + { + var api = new TrippinApi(); + api.CanExecuteResetDataSource.Should().BeFalse(); + } + + #endregion + + #region Test Helpers + + /// + /// Sets the Thread.CurrentPrincipal to a test user with an "admin" Role Claim. + /// + internal static void AuthenticateAsAdmin() + { + var claimsCollection = new List + { + new Claim(ClaimTypes.Role, "admin") + }; + var claimsIdentity = new ClaimsIdentity(claimsCollection, "Test User"); + Thread.CurrentPrincipal = new ClaimsPrincipal(claimsIdentity); + } + + /// + /// Sets the Thread.CurrentPrincipal to a test user without an "admin" Role Claim. + /// + internal static void AuthenticateAsNonAdmin() + { + var claimsCollection = new List(); + var claimsIdentity = new ClaimsIdentity(claimsCollection, "Test User"); + Thread.CurrentPrincipal = new ClaimsPrincipal(claimsIdentity); + } + + #endregion + + } + +} + +``` \ No newline at end of file diff --git a/docs/server/method-authorization.md b/docs/server/method-authorization.md new file mode 100644 index 00000000..7013fc55 --- /dev/null +++ b/docs/server/method-authorization.md @@ -0,0 +1,352 @@ +# Method Authorization + +Method Authorization allows you to have fine-grain control over how different types of API requests can be executed. +Since most of RESTier uses built-in convention over repetitive boiler-plate Controllers, you can't just add security attributes +to the controller methods, like you can with Web API. + +However, there are two different methods for defining per-request security. One, like the rest of RESTier, is +convention-based, and the other executes before every request, allowing you to centralize your authorization logic. +This allows you to pick the approach that works best for your architecture. + +No matter what approach you chose, the concept is simple. Either technique uses a function that returns boolean. +Return `true`, and processing continues normally. Return `false`, and RESTier returns a 403 Unauthorized to the client. + +## Convention-Based Authorization +Users can control if one of the four submit operations is allowed on some EntitySet or Action by putting some +`protected internal` methods into the `Api` class. The method name must conform to the convention +`Can{Operation}{TargetName}`. + + + + + + + + + + +
The possible values for {Operation} are:The possible values for {TargetName} are:
+
    +
  • Insert
    • +
  • Update
    • +
  • Delete
    • +
  • Execute
    • +
+ 		+
    +
  • EntitySetName
    • +
  • ActionName
    • +
+
+ +### Example + +The example below demonstrates how both types of `{TargetName}` can be used. + +- The first method shows a simple way to prevent *any* user from deleting a particular EntitySet. +- The second method shows how you can integrate role-based security using multiple techniques. +- The third method shows how to prevent execution a custom Action. + +```cs +using Microsoft.Restier.Providers.EntityFramework; +using System; +using System.Security.Claims; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Specifies whether or not a Trip can be deleted from an EntitySet. + /// + protected internal bool CanDeleteTrips() + { + return false; + } + + /// + /// User role-based security to specifies whether or not a updated Trip can be sent to an EntitySet. + /// + protected internal bool CanUpdateTrips() + { + // Use claims-based security + return ClaimsPrincipal.Current.IsInRole("admin"); + + // You can also use legacy role-based security, though it's harder to test. + //return HttpContext.Current.User.IsInRole("admin"); + } + + /// + /// Specifies whether or not an Action called ResetDataSource can be executed through the API. + /// + protected internal bool CanExecuteResetDataSource() + { + return false; + } + + } + +} +``` + +## Centralized Authorization + +In addition to the more granular convention-based approach, you can also centralize processing into one location. This is +useful if + +User can use interface `IChangeSetItemAuthorizer` to define any customize authorize logic to see whether user is +authorized for the specified submit, if this method return false, then the related query will get error code 403 (Forbidden). + +There are two steps to plug in the centralized authorization logic. + +- Create a class that implements `IChangeSetItemAuthorizer`. +- Register that class with RESTier through Dependency Injection (DI). + +### Example + +```cs +using Microsoft.OData.Core; +using Microsoft.Restier.Providers.EntityFramework; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// Provides global ChangeSet Authorization for a RESTier API. + /// + public class CustomAuthorizer : IChangeSetItemAuthorizer + { + + /// + /// + /// + public Task AuthorizeAsync(SubmitContext context, ChangeSetItem item, CancellationToken cancellationToken) + { + // TODO: RWM: Provide legitimate samples here, along with parameter documentation. + } + + } + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Allows us to leverage DI to inject additional capabilities into RESTier. + /// + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + return base.ConfigureApi(services) + .AddService(); + } + + } + +} +``` + +## Leveraging Both Techniques + +There may be certain situations where you want to have a global interceptor, and then pass requests off to the individual +convention-based interceptors. For example, if you need to authenticate a Bearer token. The example below shows you +exactly how this type of scenario would work. + +### Example + +```cs +using Microsoft.OData.Core; +using Microsoft.Restier.Providers.EntityFramework; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + + /// + /// Provides global ChangeSet Authorization for a RESTier API. + /// + public class CustomAuthorizer : IChangeSetItemAuthorizer + { + + /// + /// The built-in ChangeSetItemAuthorizer instance that will be set by RESTier. + /// + private IChangeSetItemAuthorizer InnerAuthorizer {get; set;} + + /// + /// + /// + public Task AuthorizeAsync(SubmitContext context, ChangeSetItem item, CancellationToken cancellationToken) + { + // TODO: RWM: Provide legitimate samples here, along with parameter documentation. + + // Hand off processing to the appropriate convention-based function. + await InnerAuthorizer.AuthorizeAsync(context, item, cancellationToken); + } + + } + + /// + /// Customizations to the EntityFrameworkApi for the TripPin service. + /// + /// + /// Add the following line in WebApiConfig.cs to register this code: + /// await config.MapRestierRoute("Trippin", "api", new RestierBatchHandler(GlobalConfiguration.DefaultServer)); + /// + public class TrippinApi : EntityFrameworkApi + { + + /// + /// Allows us to leverage DI to inject additional capabilities into RESTier. + /// + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + return base.ConfigureApi(services) + .AddService(); + } + + } + +} +``` + +## Unit Testing Considerations + +Because both of these methods are de-coupled from the code that interacts with the database, the Authorization +logic is easily testable, without having to fire up the entire Web API + RESTier pipeline. + +### Setting up your Unit Test + +If you don't have a unit test project for your API project already, start by creating one. Repeat the process +outlined in "Getting Started" to install the RESTier packages into your Unit Test project. The add the FluentAssertions +package. + +Next, go back to your API project. Expand the "Properties" node, double-click AssemblyInfo.cs, and add the following line +to the very end of the file: `[assembly: InternalsVisibleTo("{TestProjectAssembly}")]`, making sure you replace +{TestProjectAssembly} with the actual assembly name. This is important, because otherwise the tests won't be able to see +the `protected internal` methods the authorization conventions use. + +### Example + +Given the [Convention-Based Authorization](#convention-based-authorization) example, the tests below should have 100% code +coverage, and should pass without any required changes. + +```cs +using FluentAssertions; +using Microsoft.OData.Core; +using Microsoft.OData.Service.Sample.Trippin.Api; +using Microsoft.Restier.Providers.EntityFramework; +using Microsoft.VisualStudio.TestTools.UnitTesting; +using System; +using System.Security.Claims; + +namespace Trippin.Tests.Api +{ + + /// + /// Test cases for the RESTier Method Authorizers. + /// + [TestClass] + public class TrippinApiTests + { + + #region Trips EntitySet + + /// + /// Tests if the Trips EntitySet is properly configured to reject delete requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanDelete_IsConfigured() + { + var api = new TrippinApi(); + api.CanDeleteTrips.Should().BeFalse(); + } + + /// + /// Tests if the Trips EntitySet is properly configured to accept Admin update requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanUpdate_IsAdmin() + { + var api = new TrippinApi(); + + // We won't be testing HttpContext-related security here, because that requires mocking, + // which is outside the scope of this document. + AuthenticateAsAdmin(); + api.CanUpdateTrips.Should().BeTrue(); + } + + /// + /// Tests if the Trips EntitySet is properly configured to reject non-Admin update requests. + /// + [TestMethod] + public void TrippinApi_Trips_CanUpdate_IsNotAdmin() + { + var api = new TrippinApi(); + // We won't be testing HttpContext-related security here, because that requires mocking, + // which is outside the scope of this document. + AuthenticateAsNonAdmin(); + api.CanUpdateTrips.Should().BeFalse(); + } + + #endregion + + #region Actions + + /// + /// Tests if the Trips EntitySet is properly configured to reject delete requests. + /// + [TestMethod] + public void TrippinApi_CanExecuteResetDataSource_IsConfigured() + { + var api = new TrippinApi(); + api.CanExecuteResetDataSource.Should().BeFalse(); + } + + #endregion + + #region Test Helpers + + /// + /// Sets the Thread.CurrentPrincipal to a test user with an "admin" Role Claim. + /// + internal static void AuthenticateAsAdmin() + { + var claimsCollection = new List + { + new Claim(ClaimTypes.Role, "admin") + }; + var claimsIdentity = new ClaimsIdentity(claimsCollection, "Test User"); + Thread.CurrentPrincipal = new ClaimsPrincipal(claimsIdentity); + } + + /// + /// Sets the Thread.CurrentPrincipal to a test user without an "admin" Role Claim. + /// + internal static void AuthenticateAsNonAdmin() + { + var claimsCollection = new List(); + var claimsIdentity = new ClaimsIdentity(claimsCollection, "Test User"); + Thread.CurrentPrincipal = new ClaimsPrincipal(claimsIdentity); + } + + #endregion + + } + +} + +``` \ No newline at end of file diff --git a/docs/server/model-building.md b/docs/server/model-building.md new file mode 100644 index 00000000..cf92abcb --- /dev/null +++ b/docs/server/model-building.md @@ -0,0 +1,277 @@ +# Customizing the Entity Model + +OData and the Entity Framework are based on the same underlying concept for mapping the idea of an Entity with +its representation in the database. That "mapping" layer is called the Entity Data Model, or EDM for short. + +Part of the beautiy of RESTier is that, for the majority of API builders, it can construct your EDM for you +*automagically*. But there are times where you have to take charge of the process. And as with many things in RESTier, +the intrepid developers at Microsoft provide you with two ways to do so. + +The first method allows you to completely relpace the automagic model construction with your own, in a manner +very similar to Web API OData. + +The second method lets RESTier do the initial work for you, and then you manipulate the resulting EDM metadata. + +Let's take a look at how each of these methods work. + +## ModelBuilder Takeover + +There are several situations where you are likely going to want to use this approach to create your Model. +For example, if you're migrating from an existing Web API OData v3 or v4 implementation, and needed to +customize that model, you will be able to copy/paste your existing code over, with just a few small changes. +If you're building a new model, but you're using Entity Framework Model First + SQL Views, then you'll +likely need to define a primary key, or omit the View from your service. + +With the Entity Framework provider, the model is built with the +[**ODataConventionModelBuilder**](http://odata.github.io/WebApi/#02-04-convention-model-builder). To +understand how this ModelBuilder works, please take a few minutes and review that documentation. + +# Example + +```cs +using Microsoft.Extensions.DependencyInjection; +using Microsoft.OData.Edm; +using Microsoft.Restier.Core; +using Microsoft.Restier.Core.Model; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using System.Web.OData.Builder; + +namespace Microsoft.OData.Service.Sample.TrippinInMemory +{ + + internal class CustomizedModelBuilder : IModelBuilder + { + public Task GetModelAsync(ModelContext context, CancellationToken cancellationToken) + { + var builder = new ODataConventionModelBuilder(); + builder.EntityType(); + return Task.FromResult(builder.GetEdmModel()); + } + } + + /// + /// + /// + public class TrippinApi : ApiBase + { + + /// + /// + /// + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + return base.ConfigureApi(services) + .AddService(); + } + + } + +} +``` + +If RESTier entity framework provider is used and user has no additional types other than those in the database schema, no +custom model builder or even the `Api` class is required because the provider will take over to build the model instead. +But what the provider does behind the scene is similar. + + + +## Extend a model from Api class +The `RestierModelExtender` will further extend the EDM model passed in using the public properties and methods defined in the +`Api` class. Please note that all properties and methods declared in the parent classes are **NOT** considered. + +**Entity set** +If a property declared in the `Api` class satisfies the following conditions, an entity set whose name is the property name +will be added into the model. + + - Public + - Has getter + - Either static or instance + - There is no existing entity set with the same name + - Return type must be `IQueryable` where `T` is class type + +Example: + +```cs +using System.Collections.Generic; +using System.Linq; +using Microsoft.Restier.Core.Model; +using Microsoft.Restier.Provider.EntityFramework; +using Microsoft.OData.Service.Sample.Trippin.Models; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + public class TrippinApi : EntityFrameworkApi + { + public IQueryable PeopleWithFriends + { + get { return Context.People.Include("Friends"); } + } + ... + } +} +``` + +**Singleton** +If a property declared in the `Api` class satisfies the following conditions, a singleton whose name is the property name +will be added into the model. + + - Public + - Has getter + - Either static or instance + - There is no existing singleton with the same name + - Return type must be non-generic class type + +Example: + +```cs +using System.Collections.Generic; +using System.Linq; +using Microsoft.Restier.Core.Model; +using Microsoft.Restier.Provider.EntityFramework; +using Microsoft.OData.Service.Sample.Trippin.Models; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + public class TrippinApi : EntityFrameworkApi + { + ... + public Person Me { get { return DbContext.People.Find(1); } } + ... + } +} +``` + +Due to some limitations from Entity Framework and OData spec, CUD (insertion, update and deletion) on the singleton entity are +**NOT** supported directly by RESTier. Users need to define their own route to achieve these operations. + +**Navigation property binding** +Starting from version 0.5.0, the `RestierModelExtender` follows the rules below to add navigation property bindings after entity + sets and singletons have been built. + + - Bindings will **ONLY** be added for those entity sets and singletons that have been built inside `RestierModelExtender`. + **Example:** Entity sets built by the RESTier's EF provider are assumed to have their navigation property bindings added already. + - The `RestierModelExtender` only searches navigation sources who have the same entity type as the source navigation property. + **Example:** If the type of a navigation property is `Person` or `Collection(Person)`, only those entity sets and singletons of type `Person` are searched. + - Singleton navigation properties can be bound to either entity sets or singletons. + **Example:** If `Person.BestFriend` is a singleton navigation property, bindings from `BestFriend` to an entity set `People` or to a singleton `Boss` are all allowed. + - Collection navigation properties can **ONLY** be bound to entity sets. + **Example:** If `Person.Friends` is a collection navigation property. **ONLY** binding from `Friends` to an entity set `People` is allowed. Binding from `Friends` to a singleton `Boss` is **NOT** allowed. + - If there is any ambiguity among entity sets or singletons, no binding will be added. + **Example:** For the singleton navigation property `Person.BestFriend`, no binding will be added if 1) there are at least two entity sets (or singletons) both of type `Person`; 2) there is at least one entity set and one singleton both of type `Person`. However for the collection navigation property `Person.Friends`, no binding will be added only if there are at least two entity sets both of type `Person`. One entity set and one singleton both of type `Person` will **NOT** lead to any ambiguity and one binding to the entity set will be added. + +If any expected navigation property binding is not added by RESTier, users can always manually add it through custom model extension (mentioned below). +
+ +**Operation** +If a method declared in the `Api` class satisfies the following conditions, an operation whose name is the method name will be added into the model. + + - Public + - Either static or instance + - There is no existing operation with the same name + +Example (namespace should be specified if the namespace of the method does not match the model): + +```cs +using System.Collections.Generic; +using System.Linq; +using Microsoft.Restier.Core.Model; +using Microsoft.Restier.Provider.EntityFramework; +using Microsoft.OData.Service.Sample.Trippin.Models; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + public class TrippinApi : EntityFrameworkApi + { + ... + // Action import + [Operation(Namespace = "Microsoft.OData.Service.Sample.Trippin.Models", HasSideEffects = true)] + public void CleanUpExpiredTrips() {} + + // Bound action + [Operation(Namespace = "Microsoft.OData.Service.Sample.Trippin.Models", HasSideEffects = true)] + public Trip EndTrip(Trip bindingParameter) { ... } + + // Function import + [Operation(Namespace = "Microsoft.OData.Service.Sample.Trippin.Models", EntitySet = "People")] + public IEnumerable GetPeopleWithFriendsAtLeast(int n) { ... } + + // Bound function + [Operation(Namespace = "Microsoft.OData.Service.Sample.Trippin.Models", EntitySet = "People")] + public Person GetPersonWithMostFriends(IEnumerable bindingParameter) { ... } + ... + } +} +``` + +Note: + +1. Operation attribute's EntitySet property is needed if there are more than one entity set of the entity type that is type of result defined. Take an example if two EntitySet People and AllPersons are defined whose entity type is Person, and the function returns Person or List of Person, then the Operation attribute for function must have EntitySet defined, or EntitySet property is optional. + +2. Function and Action uses the same attribute, and if the method is an action, must specify property HasSideEffects with value of true whose default value is false. + +3. In order to access an operation user must define an action with `ODataRouteAttribute` in his custom controller. +Refer to [section 3.3](http://odata.github.io/RESTier/#03-03-Operation) for more information. + +## Custom model extension +If users have the need to extend the model even after RESTier's conventions have been applied, user can use IServiceCollection AddService to add a ModelBuilder after calling base.ConfigureApi(services). + +```cs +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.OData.Edm; +using Microsoft.Restier.Core; +using Microsoft.Restier.Core.Model; +using Microsoft.Restier.Provider.EntityFramework; +using Microsoft.OData.Service.Sample.Trippin.Models; + +namespace Microsoft.OData.Service.Sample.Trippin.Api +{ + public class TrippinAttribute : ApiConfiguratorAttribute + { + protected override IServiceCollection ConfigureApi(IServiceCollection services) + { + services = base.ConfigureApi(services); + // Add your custom model extender here. + services.AddService(); + return services; + } + + private class CustomizedModelBuilder : IModelBuilder + { + public IModelBuilder InnerModelBuilder { get; set; } + + public async Task GetModelAsync(InvocationContext context, CancellationToken cancellationToken) + { + IEdmModel model = null; + + // Call inner model builder to get a model to extend. + if (this.InnerModelBuilder != null) + { + model = await this.InnerModelBuilder.GetModelAsync(context, cancellationToken); + } + + // Do sth to extend the model such as add custom navigation property binding. + + return model; + } + } + } +} +``` + +After the above steps, the final process of building the model will be: + + - User's model builder registered before base.ConfigureApi(services) is called first. + - RESTier's model builder includes EF model builder and RestierModelExtender will be called. + - User's model builder registered after base.ConfigureApi(services) is called. +
+ +If InnerModelBuilder method is not called first, then the calling sequence will be different. +Actually this order not only applies to the `IModelBuilder` but also all other services. + +Refer to [section 4.3](http://odata.github.io/RESTier/#04-03-Api-Service) for more details of RESTier API Service. diff --git a/docs/vs-highlight.css b/docs/vs-highlight.css new file mode 100644 index 00000000..e94200f2 --- /dev/null +++ b/docs/vs-highlight.css @@ -0,0 +1,81 @@ +/* +Visual Studio-like style based on original C# coloring by Jason Diamond +*/ +.hljs { + display: block; + overflow-x: auto; + padding: 0.5em; + background: white; + color: black; +} + +.hljs-comment, +.hljs-quote, +.hljs-variable { + color: #008000; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-built_in, +.hljs-name, +.hljs-tag { + color: #00f; +} + +.hljs-string, +.hljs-title, +.hljs-section, +.hljs-attribute, +.hljs-literal, +.hljs-template-tag, +.hljs-template-variable, +.hljs-type, +.hljs-addition { + color: #a31515; +} + +.hljs-deletion, +.hljs-selector-attr, +.hljs-selector-pseudo, +.hljs-meta { + color: #2b91af; +} + +.hljs-doctag { + color: #808080; +} + +.hljs-attr { + color: #f00; +} + +.hljs-symbol, +.hljs-bullet, +.hljs-link { + color: #00b0e8; +} + + +.hljs-emphasis { + font-style: italic; +} + +.hljs-strong { + font-weight: bold; +} + +code { + font-size: 80%; +} + +td code { + font-size: 100%; +} + +.wy-menu-vertical .subnav li.current > a { + padding-left: 2.42em; +} +.wy-menu-vertical .subnav li.current > ul li a { + padding-left: 3.23em; +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..2d75fc54 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,31 @@ +site_name: RESTier Documentation +site_description: How to use the RESTier framework for .NET. +theme: readthedocs +pages: +- Home: + - 'Introduction': 'index.md' + - 'Getting Started': 'getting-started.md' +- Building the Service: + - 'Entity Set Filters': 'server/filters.md' + - 'Method Authorization': 'server/method-authorization.md' + - 'Interceptors': 'server/interceptors.md' + - 'Model Building': 'server/model-building.md' +- Extending RESTier: + - 'Temporal Types': 'extending-restier/temporal-types.md' + - 'In-Memory Provider': 'extending-restier/in-memory-provider.md' + - 'Additional Operations': 'extending-restier/additional-operations.md' +- Building the Client: + - '.NET': 'clients/dot-net.md' +- Release Notes: + - 0.5.0-beta: 'release-notes/0-5-0-beta.md' + - 0.4.0-rc2: 'release-notes/0-4-0-rc2.md' + - 0.4.0-rc: 'release-notes/0-4-0-rc.md' + - 0.3.0-beta2: 'release-notes/0-3-0-beta2.md' + - 0.3.0-beta1: 'release-notes/0-3-0-beta1.md' +- About: + - 'License': 'license.md' + - 'Contributing': 'contribution-guidelines.md' +extra_css: [vs-highlight.css] +markdown_extensions: + - toc: + baselevel: "1" \ No newline at end of file