add more details

doc/microsoft_graph_client.md

@@ -1,4 +1,4 @@
-# `GraphClient` - Microsoft Graph API client 
+# `GraphClient` - Microsoft Graph API client
 
 Azure CLI has been migrated to Microsoft Graph API for Azure Active Directory operations. A lightweight client `azure.cli.command_modules.role._msgrpah.GraphClient` is developed for calling Microsoft Graph API.
 
@@ -16,7 +16,50 @@ from azure.cli.command_modules.role._msgrpah import GraphClient
 graph_client = GraphClient(cli_ctx)
 ```
 
-## Example
+## Request
+
+The underlying Microsoft Graph API is exposed as `GraphClient` methods. For example, [Create application](https://docs.microsoft.com/en-us/graph/api/application-post-applications) API corresponds to `application_create`.
+
+The order of the verb ("create") and the noun ("application") is inverted to keep alignment with Azure CLI commands like `az ad app create` and old Python SDK `azure-graphrbac` methods like `graph_client.applications.create`. This makes it easier to find a method/API from the new `GraphClient` and migrate to it:
+
+```diff
+- graph_client.applications.create(app_create_param)
++ graph_client.application_create(body)
+```
+
+The `body` argument for the request should be a `dict` object as defined by the underlying API. For example, [Create application](https://docs.microsoft.com/en-us/graph/api/application-post-applications) takes a `dict` object defined by [application resource type](https://docs.microsoft.com/en-us/graph/api/resources/application).
+
+For example, to create an application with certain `displayName`:
+
+```py
+body = {"displayName": display_name}
+app = graph_client.application_create(body)
+```
+
+## Response
+
+Like `body`, the response is also a `dict` object, returned by the underlying API. The `dict` object is deserialized from the JSON response, **unchanged**, meaning any client-side manipulation defined by REST API spec (such as flattening) doesn't take place.
+
+For example, to get an application's object ID:
+
+```py
+app_object_id = app['id']
+```
+
+## Error
+
+All `GraphClient` methods raise an `azure.cli.command_modules.role.GraphError` exception if the underlying APIs return a status code >= 400.
+
+Say we catch the exception as `ex`. `str(ex)` gives the `error.message` field of the response JSON. `ex.response` gives the raw response, as a `requests.models.Response` object.
+
+For example, to retrieve the error message and status code:
+
+```py
+message = str(ex)
+status_code = ex.response.status_code
+```
+
+## A full example
 
 Here is a full example `graph_demo.py`. It does several tasks: