/microsoft-graph-devx-content

Content used by the DevX API to enhance clients and tooling.

Primary LanguageJavaScriptMIT LicenseMIT

microsoft-graph-devx-content

Content used by the DevX API to enhance clients and tooling. At the moment it has:

  • Permissions
  • Samples

This will also be used by the localization team to add translation files, and by feature teams to modify, add, or update samples.

Contributing

Adding Sample Queries

Pre-requisites:

  1. Download and Install Git to your machine https://git-scm.com/downloads
  2. Download and Install VS Code to your machine https://code.visualstudio.com/download

To add sample queries follow these steps:

  1. Clone or fork this repo (microsoft-graph-devx-content) in your local machine.
  2. Navigate to the file sample-queries.json in the sample-queries folder.
  3. Open the file sample-queries.json on your favourite editor (e.g VS Code)
  4. If you are adding a new category (workload) sample (e.g. Teams, Excel), add the queries at the end of the list right before the closing square bracket ] in the following format. However, if you are adding a sample query to an existing category, find it on the document and add the query next to the other queries in that category.
    GET example 
 {
  "id": "76ecc500-897d-4a5e-a15c-0f6702a43d32",
  "category": "Extensions",
  "method": "GET",
  "humanName": "get available schema extensions",
  "requestUrl": "/v1.0/schemaExtensions",
  "docLink": "https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/schemaextension_post_schemaextensions",
   "skipTest": false
  },
  • id - generate a GUID here: https://guidgenerator.com/
  • category - the workload category the sample query falls under e.g. Teams, Outlook, Extensions etc
  • method - request option, e.g GET, POST, PUT, PATCH, DELETE
  • humanName - the name users will see on Graph Explorer UI describing what the sample query does
  • requestUrl - the url to query the sample query on Graph API, but dont put the https://graph.microsoft.com bit of the url
  • docLink - link to the sample query documentation.
  • skipTest - this is always false for all sample queries

POST Example includes headers, post body and a tip

{
"id": "9b937d40-885d-4eb1-a36d-9b001ce63d1d",
"category": "OneNote",
"method": "POST",
"humanName": "create section",
"requestUrl": "/v1.0/me/onenote/notebooks/{notebook-id}/sections",
"docLink": "https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/api/notebook_post_sections",
"headers": [
{
"name": "Content-type",
"value": "application/json"
}
],
"postBody": "{\r\n \"displayName\": \"Section 1\"\r\n}",
"tip": "This query requires a notebook id. To find the ID, you can run: GET https://graph.microsoft.com/v1.0/me/onenote/notebooks. ",
"skipTest": false<br> },

  • headers - add the headers required to run the POST query
  • postBody - add the post body required to run the query
  • tip - include a tip giving more information to the user on things like permissions required, and how to get an id if needed.

When done making the changes on the document,

  1. Save the document on your machine
  2. Create a Git branch on this repo and name it using your initials + describe the changes ie. bn/add-xyz-samples
  3. Commit the changes to your branch
  4. Create a PR and add Bettirose Ngugi and/or Irvine Sunday as the reviewer(s).

Once the PR is reviewed and merged, the changes will appear on Graph Explorer in 2 working days.

Please note that:

  1. The order of properties is as outlined below (where applicable for your sample)
    "id":
    "category":
    "method":
    "humanName":
    "requestUrl":
    "docLink":
    "headers":
    "postBody":
    "tip":
    "skipTest":
  2. The humanName value should be in small caps only.
  3. The requestUrl value should be a relative url, starting from the version, i.e. "requestUrl": "/v1.0/me/onenote/notebooks/{notebook-id}/sections" leave out the https://graph.microsoft.com part of the url.

Using Command Line or PowerShell:

1. Clone or Fork the repo

Open the command line terminal and paste this command to clone or fork this repo:
git clone https://github.com/microsoftgraph/microsoft-graph-devx-content.git microsoft-graph-devx-content cd microsoft-graph-devx-content/sample-queries

2. Open the sample-queries.json file

To open the sample-queries.json file, paste in this command:
code -n sample-queries.json

Alternatively, you can open the directory where the file is located by pasting in this command:
start .

3. Open the Git command utility

If your machine's OS/CPU is x64, paste in this command:
start "%PROGRAMFILES%\Git\bin\sh.exe" --login else, if x86, paste in this command:
start "%SYSTEMDRIVE%\Program Files (x86)\Git\bin\sh.exe"

4. Create your local branch

Your branch name has to be of the format: {your-intial}/{purpose-of-change}. Replace the text within the curly braces (inclusive of the curly braces).
Then in the new Git command line window, paste in this command to create and checkout your branch:
git checkout -b {your-branch-name}

5. Update your sample query

Now you can add, update or delete your sample query in the sample-queries.json file that opened up in VS Code earlier.

6. Add, commit and push your changes back to the remote repo with the following commands

  • Add the changes to you local repo: git add sample-queries.json
  • Commit your changes: git commit -m "{add-reason-for-update}"
  • Push your changes to the remote repo: git push origin {your-branch-name}

7. Login to GitHub

Follow the instructions to login to GitHub using your credentials.

8. If you get error 403

Follow the instructions specified, then run this command again:
git push origin {your-branch-name}

Testing of Sample Queries

Once you've added/updated the sample queries, you can test them out by going to Graph Explorer, and appending this to the end of the Graph Explorer url.

?devx-api=https://graphexplorerapi.azurewebsites.net&org={org}&branchName={branchName}

This fetches the permissions/samples from your specific branch or repo.

Full url/path format:

https://developer.microsoft.com/en-us/graph/graph-explorer?devx-api=https://graphexplorerapi.azurewebsites.net&org={org}&branchName={branchName}

NB:

i. Replace {branchName} with the name of your current branch.

ii. In the case of a forked repo, replace the {org} parameter with your Github username. iii. If your branch is in this repo, replace {org} with microsoftgraph

Example:

https://developer.microsoft.com/en-us/graph/graph-explorer?devx-api=https://graphexplorerapi.azurewebsites.net&org=MeganBowen&branchName=mk/update-sample

The samples/permissions will be populated on Graph Explorer and you can do further testing.

Please Note:

In case you see You are viewing a cached set of samples because of a network connection failure, check the query parameters and confirm they're correct, then reload the page.

If you run into any issues, reach out to @BettiroseNgugi