Odata Documentation

[FIVIL]

I want to add a few articles (and code examples as well) about Odata support in ASP.net core so as required in CONTRIBUTING.md file for complex submissions i opened this issue to get approval for them.
what i have in mind is a simple example of adding odata capabilities on top of existing API and also some tips for scenarios which include starting a new API project with odata support from scratch.
also i come across this (#9740) open issue about odata so i was wondering should i do it or wait for odata official team.
also i think it worth to mention that im having 1.5+ years experience with ASP.net core and 3+ years experience with C# and ASP.net mvc (.net framework) and also good understanding of odata.

@Rick-Anderson edit:

Reopen this and PR #12108 When MicrosoftDocs/OData-docs#74 is merged. Look for closed issues with ODATA in:title

[Rick-Anderson]

@FIVIL thanks for checking first. @blowdart and @HaoK will make that decision. They'll probably want an outline before you start.

[blowdart]

As long as the security implications and mitigations are covered I have no problems.

[Rick-Anderson]

@FIVIL can you post an outline here?

[FIVIL]

@Rick-Anderson Sure.
as i mentioned earlier what i have in mind contains two separate parts which are

1. Adding OData support to a existing REST API
2. Creating a new REST API with OData support

for the first one i do not intend going into details so ill make a single article .
in this single article i will explain how you can add OData support to your existing API with as less modification as possible in your codebase without breaking the existing API routes with backward compatibilities.
in this article i will expand this already existing project in docs, though i might change the model class for better demonstration of OData capabilities by adding some new properties
the outline will look like this:

1. Overview
   -what we are going to build-
2. Prerequisites
   -VS 2017+ and .ner core SDK 2+-
3. Introduction
   -what is OData-
4. Loading the project
   -which as i mentioned in this step i will show how you can load the existing project in VS-
5. Adding Nuget Packages
   -i will use this official package from MS-
6. Updating Model Class
   -adding some new properties to use OData capabilities-
7. Adding migratings
8. Registering required services in DI container
9. Configuring middlewares
   -i will show how you can add OData route and also how you can expand your existing API routes using routeBuilder.EnableDependencyInjection();-
10. Changes in Controllers
11. some example
    -how to invoke new api methods using OData queries-
12. Security concerns
    -how you can prevent or add some OData features-
13. Additional resources
    ill try to make this article as short and as simple as possible

also i will add some code examples and i might include some screenshots from postman to showing the result of invoking the API

for the second part i intend to make a couple of articles and in them i will go further into details and internals of OData
Outline:
article number 1 -> Overview : what the end result would look like and link to other articles in this series
article number 2 -> complete introduction to OData, explaining that how OData is actually a open specification and .net core libraries, also i will dive into query language and functionalities of OData
article number 3 -> Getting Started

1. Prerequisites
2. Creating The Project
3. Adding Nuget Packages
4. Running the Project to make sure everything is fine

article number 4 -> adding model classes:
in this step i will use the contos university example which is a well understood example from MS
article number 5 -> Configuring Database:

1. Adding database context class
2. Adding migrations

article number 6 -> Configurations of the project:

1. Adding Services in DI container
2. Adding middlewares with much more details

article number 7 -> Scaffolding

1. Scaffolding the Controllers
2. Applying required changes to the controllers

article number 8 -> Pushing some data into API
article number 9 -> Examples:

1. querying data
2. querying a single record
3. filters
4. querying relational data
5. invoking functions

article number 10 -> Security concerns

so im expecting to do this in at least 3 RRs one for article number 1, one for series of articles in 2nd part and one last PR for code examples

[Rick-Anderson]

Looks good to me.
@blowdart and @HaoK any comments on the outline?

[Rick-Anderson]

@FIVIL would you be interested in helping @guardrex with #5106?

[FIVIL]

@Rick-Anderson Sure, honestly im having some spare time within next few month and i want to get best out of it by contributing to aspnet repos, so im open to help with any task that can be done by community.
also im waiting for @blowdart and @HaoK approval for OData doc outline so i can get started on them as well.

[guardrex]

I think #5106 provides what I need to perform the update. Within Tratcher's remarks, I see about three aspects missing from the topic. @FIVIL, I'll ping u on the PR to review it if you have time.

[FIVIL]

@guardrex sounds great to me, so im waiting to hear from you.

[Rick-Anderson]

@FIVIL ping me next week if @blowdart doesn't approve your outline. @scottaddie / @danroth27 please review outline.

[blowdart]

Harsh but fair @Rick-Anderson.

Security to 10 maybe? My concern here is, for example, someone reads enough to expose their data because that's what they want to do, without understanding they now have a DoS vector or Information Leak via joins.

Notes in each section to the security section would work though, so no objections to the outline

[FIVIL]

@blowdart sure, ill keep your notes in mind.

[FIVIL]

so im trying to deliver first draft as soon as possible.

[FIVIL]

@Rick-Anderson
I'm done with the first set of tutorials, however, I will cover more materials in the next set of articles.
you can check out the sample files in:
https://github.com/FIVIL/AspNetCore.Docs/tree/OData/aspnetcore/tutorials/first-odata-api/samples/2.2/TodoApi
and markdown file in:
https://github.com/FIVIL/AspNetCore.Docs/blob/OData/aspnetcore/tutorials/first-odata-api.md
and tell me if they are Ok, so i can send a PR, or if they need any changes

TNX

[Rick-Anderson]

@FIVIL looks great. Create a PR then I'll submit some commits to your branch for minor edits.

[Rick-Anderson]

@FIVIL when you submit the PR, @mention me only so I have a chance to make some edits, then we can mention @blowdart

[Rick-Anderson]

@FIVIL I moved two of them over - see https://docs.microsoft.com/en-us/odata/webapi/odata-expand
The last one is in PR at MicrosoftDocs/OData-docs#83