microsoftgraph / microsoft-graph-devx-api Goto Github PK

View Code? Open in Web Editor NEW

86.0 30.0 31.0 10.26 MB

Services API for Graph Explorer

License: MIT License

C# 98.77% HTML 0.28% PowerShell 0.95%

devxeng

microsoft-graph-devx-api's People

Contributors

Stargazers

Watchers

microsoft-graph-devx-api's Issues

Permissions API

Currently, one needs to manually assign themselves permissions to run specific queries.
With this API GE will be able to detect the query parameters and suggest the permissions that the user needs to request. This makes the experience way easier for the developers. Microsoft workloads can call secured API to add new permissions

Add suppression for failures due to snippets import to ensure PR passes

Currently this PR https://github.com/microsoftgraph/microsoft-graph-docs/pull/4276 is failing due to APIDoctor checks. In order to ensure that we can get the PR out on Friday, we should suppress this error.

/cc @jthake-msft

Escape existing double quotes present in header

Ensure that double quotes are escaped on generation of code that involves headers.
See example here

Create Snippets for GET requests

Autocomplete API

This is an intelligent API that can detect the query that the user is typing and give appropriate suggestions. Depending on the query type the API will give the appropriate request types as options. One doesn't have to remember the query parameters since the APi will have a Query Builder from where a user can pick the parameters, they wish to add to their query parameter.

Provide checks to use pluralized variables names when accessing collections

Looking at this sample

GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = await graphClient.Users
    .Request()
    .Select( e => new {
             e.DisplayName,
             e.GivenName,
             e.PostalCode 
             })
    .GetAsync();

The variable name used is in singular but we are actually returning a collection of users.

We can use this library https://www.nuget.org/packages/Pluralize.NET.Core/ to pluralize variable names when we need to.

CSharp sample is missing for Create Mail Search Folder

https://docs.microsoft.com/en-us/graph/api/mailsearchfolder-post?view=graph-rest-beta&tabs=javascript

Generate Select expression

Add support for Actions and Functions - ODataUriParser does not support Functions and Actions

Add support for custom query options

Add support for the custom query options that maybe present in requests.

An example request is found here.

Can we use the term HttpMethod instead of HttpVerb?

HTTP calls them methods, the use of "verb" is a common error. https://tools.ietf.org/html/rfc7231#section-4.3

Rename ValuesController to something more appropriate

Create snippets for POST requests for Javascript and C#

Java Code Generation

Add link to SDK docs below the sample.

Currently the sample shows as:

Please add the following text to immediately below the sample:

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Accept MailTipsType enum as second parameter to GetMailTips for C#

GetMailTips snippet should accept MailTipsType enum and not a string for C#.

Expected snippet should look like this:

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var emailAddressesList = new List<String>();
emailAddressesList .Add( "[email protected]" );
emailAddressesList .Add( "[email protected]" );

// Use MailTipsType enum.
var mailTipsOptions = MailTipsType.AutomaticReplies | MailTipsType.MailboxFullStatus;

await graphClient.Me
	.GetMailTips(emailAddressesList, mailTipsOptions)
	.Request()
	.PostAsync()

Add support for $ref scenarios in Csharp

Snippet generator should support $ref scenarios in C# by adding the "Reference" section to the Resources path.

The code refererenced in these issues should therefore look like this.

microsoftgraph/msgraph-sdk-dotnet#494
https://github.com/microsoftgraph/microsoft-graph-docs-contrib/issues/7035

await graphClient.Groups[""].Owners[""].Reference.Request().DeleteAsync();

Generate Request Builder Paths from Request URL

Can we create a proposal for what the API shape is going to look like?

Can we identify the resources we need (is there only one?) and what are the parameters we need to pass?

Generate request Headers

Lifetime of metadata

We can't afford to be retrieving and parsing the metadata on every snippet request. We will need to create an singleton service and inject it into the controller so that we can maintain parsed version of each version of the metadata in memory.

https://github.com/microsoftgraph/microsoft-graph-explorer-api/blob/345111d820b99b7b39afacd7e9e4879a1eac95a9/CodeSnippetsReflection/SnippetsGenerator.cs#L29

Use HttpRequestMessage as your model

https://github.com/microsoftgraph/microsoft-graph-explorer-api/blob/345111d820b99b7b39afacd7e9e4879a1eac95a9/CodeSnippetsReflection/SnippetsGenerator.cs#L50

Don't copy the properties of HttpRequestMessage over into RequestPayloadModel. Just use the HttpRequestMessage as your model.

Make C# object construction more concise with object initializers

Currently we generate objects using an intermediate variable,

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var emailAddress = new EmailAddress
{
	Address = "[email protected]",
	Name = "Samantha Booth",
};

var attendees = new Attendee
{
	EmailAddress = emailAddress,
	Type = AttendeeType.Required,
};

var attendeesList = new List<Attendee>();
attendeesList.Add( attendees );

var location = new Location
{
	DisplayName = "Harry's Bar",
};

var end = new DateTimeTimeZone
{
	DateTime = "2017-04-15T14:00:00",
	TimeZone = "Pacific Standard Time",
};

var start = new DateTimeTimeZone
{
	DateTime = "2017-04-15T12:00:00",
	TimeZone = "Pacific Standard Time",
};

var body = new ItemBody
{
	ContentType = BodyType.Html,
	Content = "Does late morning work for you?",
};

var event = new Event
{
	Subject = "Let's go for lunch",
	Body = body,
	Start = start,
	End = end,
	Location = location,
	Attendees = attendeesList,
};

await graphClient.Me.Events
	.Request()
	.AddAsync(event);

however there is a more concise syntax that looks like this,

            var event1 = new Event
            {
                Subject = "Let's go for lunch",
                Body = new ItemBody
                {
                    ContentType = BodyType.Html,
                    Content = "Does late morning work for you?",
                },
                Start = new DateTimeTimeZone
                {
                    DateTime = "2019-04-23T12:00:00",
                    TimeZone = "Pacific Standard Time",
                },
                End = new DateTimeTimeZone
                {
                    DateTime = "2019-04-23T14:00:00",
                    TimeZone = "Pacific Standard Time",
                },
                Location = new Location
                {
                    DisplayName = "Harry's Bar",
                },
                Attendees = new List<Attendee>() {
                    new Attendee
                    {
                        EmailAddress = new EmailAddress
                        {
                            Address = "[email protected]",
                            Name = "Samantha Booth",
                        },
                        Type = AttendeeType.Required,
                    },
                }
            };

We should evaluate how much work it might take to generate this.

Create test project using xUnit for testing

We should start creating unit tests for the snippet generator. It will make our progress faster in the long run.

Accept text/message as input to the API

Provide checks for reserved words in variable names

The following snippet generated contains the reserved word "event" as a variable name in C#.

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var emailAddress = new EmailAddress
{
	Address = "[email protected]",
	Name = "Samantha Booth",
};

var attendees = new Attendee
{
	EmailAddress = emailAddress,
	Type = AttendeeType.Required,
};

var attendeesList = new List<Attendee>();
attendeesList.Add( attendees );

var location = new Location
{
	DisplayName = "Harry's Bar",
};

var end = new DateTimeTimeZone
{
	DateTime = "2017-04-15T14:00:00",
	TimeZone = "Pacific Standard Time",
};

var start = new DateTimeTimeZone
{
	DateTime = "2017-04-15T12:00:00",
	TimeZone = "Pacific Standard Time",
};

var body = new ItemBody
{
	ContentType = BodyType.Html,
	Content = "Does late morning work for you?",
};

var event = new Event
{
	Subject = "Let's go for lunch",
	Body = body,
	Start = start,
	End = end,
	Location = location,
	Attendees = attendeesList,
};

await graphClient.Me.Events
	.Request()
	.AddAsync(event);

Ideally variable names should not be reserved words for the language in use.

Errors in Send Mail snippet

The send mail snippet has a couple of errors.
https://docs.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0&tabs=cs

The emailAddress is declared twice.
The variable saveToSentItems should be assigned a boolean variable and not a string.

Get the actual return type

Providing the actual return type versus implicitly typing the variable would provide more value.

There are business rules for determining the return type. For example, for collections, it is I*CollectionPage, where * is the return type in the collection with an optional name of the OData action. IMailFolderDeltaCollectionPage is an example of this.

Originally posted by @andrueastman in #41 (comment)
AB#7030

Objective C Code Generation

Move existing snippets in docs up to the request section

Current snippets appear after the response section in the docs. It would be great if the snippets were added as a tab section right next to the request section.,

Generate Expand expression

Setup CI for pull requests and release.

Create CI for validation of new PRs,

dev branch needs to be updated from master

Code fence for CSharp is not displaying correctly

I believe the code fence should be csharp and not cs.

Update select expressions to use anonymous objects rather that comma separated strings

Rather than use comma delimited list as the parameter for select expressions like in the example below

var event = await graphClient.Me.Events
	.Request()
	.Header("Prefer","outlook.timezone=\"Pacific Standard Time\"")
	.Select("subject,body,bodyPreview,organizer,attendees,start,end,location")
	.GetAsync();

Use an anonymous object for select expression like this:-

var event = await graphClient.Me.Events.Request()
       .Header("Prefer","outlook.timezone=\"Pacific Standard Time\"")
       .Select(e => new { e.Subject,
                          e.Body,
                          e.bodyPreview,
                          e.organizer,
                          e.attendees,
                          e.start,
                          e.end,
                          e.location 
                         })
       .GetAsync();

This provides a strongly typed experience and would be good for the snippets to show this as a best practice.

Incorrect C# constructor generation

Looking at the sample below,

Recipient does not have a constructor that accepts email address. The property needs to be set explicitly
ContentType is an enum not a string.

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var value = "NV001";

var name = "x-custom-header-group-id";

var valueVar = "Nevada";

var nameVar = "x-custom-header-group-nameVar";

//create InternetMessageHeader list and populate it
var internetMessageHeaders = new List<InternetMessageHeader>();
internetMessageHeaders.Add(new InternetMessageHeader(nameVar,valueVar));
internetMessageHeaders.Add(new InternetMessageHeader(name,value));

//create instance of EmailAddress
var emailAddress = new EmailAddress
{
	Address = "[email protected]",
};

//create Recipient list and populate it
var toRecipients = new List<Recipient>();
toRecipients.Add(new Recipient(emailAddress));

//create instance of ItemBody
var body = new ItemBody
{
	ContentType = "HTML",
	Content = "The group represents Nevada.",
};

//create instance of Message
var message = new Message
{
	Subject = "9/9/2018: concert",
	Body = body,
	ToRecipients = toRecipients,
	InternetMessageHeaders = internetMessageHeaders,
};

await graphClient.Me
	.SendMail(message,saveToSentItems)
	.Request()
	.PostAsync()

Create snippets for DELETE requests for Javascript and C#

Generate Filter Expression

C# Enums not looked up in object construction

Looking at the sample below,

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var value = "NV001";

var name = "x-custom-header-group-id";

var valueVar = "Nevada";

var nameVar = "x-custom-header-group-nameVar";

//create InternetMessageHeader list and populate it
var internetMessageHeaders = new List<InternetMessageHeader>();
internetMessageHeaders.Add(new InternetMessageHeader(nameVar,valueVar));
internetMessageHeaders.Add(new InternetMessageHeader(name,value));

//create instance of EmailAddress
var emailAddress = new EmailAddress
{
	Address = "[email protected]",
};

//create Recipient list and populate it
var toRecipients = new List<Recipient>();
toRecipients.Add(new Recipient(emailAddress));

//create instance of ItemBody
var body = new ItemBody
{
	ContentType = "HTML",
	Content = "The group represents Nevada.",
};

//create instance of Message
var message = new Message
{
	Subject = "9/9/2018: concert",
	Body = body,
	ToRecipients = toRecipients,
	InternetMessageHeaders = internetMessageHeaders,
};

await graphClient.Me
	.SendMail(message,saveToSentItems)
	.Request()
	.PostAsync()

The ContentType member in ItemBody should be an enum and not a string. Snippet generation should look up enum types as well.

Entity navigation to items in a collection is incorrect

Entity navigation to an item in a collection should use an indexer to access the item.

Expected

var messages = await graphClient.Me.Messages["event-message-id"].Request().GetAsync();

Actual

var messages = await graphClient.Me.Messages.Messages.Request().GetAsync();

andrueastman/microsoft-graph-docs@aa59672#diff-79feffb7fc74e1610b93cacecad56559R181

Create snippets for PATCH requests for Javascript and C#

Change sample code title to "SDK Sample Code"

Currently the samples show as:

Please change the title to "SDK Sample Code" instead of just "Sample Code"

Changes API

This API will detect changes in Graph API and notify users in Graph Explorer with a blue star on the samples with changes.
Requires intelligent mapping on the url to detect the query that the user types and checks if it has changed in the recent past.

Snippet Generation for Structural properties in C#

The support on the Graph SDK for accessing structural properties needs to catered for and therefore using a direct url isn't correct.

More info can be found on the issue raised here

Snippet generation on the C# needs to be refactored to cater for this.

Samples API

Adding a new sample to Graph Explorer at the moment is very complicated and a manual process.
This API will automate the process allowing one to just add a HTTP request when adding a new sample and the API takes care of the rest of the process. At the moment, with every sample added, a deployment must be done, with this API there will be no need for deployment to create a new sample. Requires securing for the API to create new samples. Reading samples can be done anonymously

I'm not sure how this code is expected to work. Where is the property assigned?
https://github.com/microsoftgraph/microsoft-graph-explorer-api/blob/345111d820b99b7b39afacd7e9e4879a1eac95a9/GraphWebApi/Controllers/GraphExplorerSnippetsController.cs#L53

I suspect we will just need to parse the first path segment to identify which version of the API we are referencing. Either that or we make it an explicit parameter.

Some pages don't get snippets.

Why does this page, or any of the "tabs" related functions not get snippets injected?
https://github.com/microsoftgraph/microsoft-graph-docs/blob/master/api-
reference/v1.0/api/teamstab-list.md

https://review.docs.microsoft.com/en-us/graph/api/teamstab-list?view=graph-rest-1.0&branch=andrueastman%2Fsnippets-preview-get-post-js-csharp

microsoftgraph / microsoft-graph-devx-api Goto Github PK

microsoft-graph-devx-api's People

Contributors

Stargazers

Watchers

Forkers

microsoft-graph-devx-api's Issues

Recommend Projects

Recommend Topics

Recommend Org