Improve graph client documentation #2498
Conversation
| ``` | ||
| | Description | Endpoint | Usage | | ||
| |--|--|--| | ||
| | List teamsApp | `GET /appCatalogs/teamsApps` | `await teamsAppsClient.list(params);` | |
There was a problem hiding this comment.
instead of "teamsAppsClient", should we use "graphClient"? And clarify that "graphClient" could come from a number of different places, and the main differences are the token that's supplied to it?
There was a problem hiding this comment.
@heyitsaamir - teamsAppsClient here is the class that implements the /appCatalogs/teamsApps/ endpoints. We can probably improve the naming of these things, but for the moment they're at least consistent for all endpoints.
The developer gets the teamsAppsClient instance from graphClient.appCatalogs.teamsApps, but I didn't want to put that in the table here. It gets too redundant and too verbose, the table becomes unreadable. I'm hoping that the note before the table and the Getting Started section at the top of each page would be sufficient for the reader to learn how to find a graph client, and then how to find these implementations too. What do you think? Would it be helpful to repeat the Getting Started link for each client type..?
Linked issues
Related to: #2480
Details
The Graph API client does not support the full and entire Microsoft Graph API surface. It's difficult for developers to understand which endpoints are actually supported and how to access them.
As a first step towards improving the graph client, this PR adds in-depth guides to show exactly which endpoints are currently supported.
Change details
The change here adds a new in-depth overview page for the graph client, and subpages for each area that is supported. The main audience for this change is someone who's already familiar with the Graph API surface and needs to understand what this library provides and how to access those features.
The documentation stops short at showing input parameter types and return values. We should add that too in the future, but this is a good start.
screenshots:
New readme.md start page:
Child page:
Attestation Checklist