diff --git a/graph-kiota/graph-kiota.md b/graph-kiota/graph-kiota.md new file mode 100644 index 0000000..7600ad5 --- /dev/null +++ b/graph-kiota/graph-kiota.md @@ -0,0 +1,135 @@ +### Graph OpenAPI description + +- [OpenAPI v1 specification](https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml) +- [OpenAPI beta specification](https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/beta/openapi.yaml) + +### Graph libraries using Kiota + +#### Graph Service library: + +The Graph Service libraries which contain the request builders will be generated using Kiota + +Generation command: +```Shell +kiota.exe -d https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml --language typescript -o path\msgraph-sdk-typescript\src -c GraphServiceClient -n MicrosoftGraph +``` +- GraphServiceClient generated. +- Request builders generated + +**Graph Core library**: + + - Graph core library takes a dependency on Kiota core. + - Kiota core contains code for a generic HTTP API. That is: + - code to call make the native HTTP client call to the API + - any generic middleware. + - Graph specific code stays in Graph core. Example: Graph Tasks. + +#### Design + + +Graph Core + +// Following is for typescript only +``` typescript +GraphCoreClient { + httpClient: KiotaHttpClient // importing the HTTPClient from Kiota core library +} +``` + +GraphServiceClient +``` +class GraphServiceClient{ + requestAdapterInstance : RequestAdapter // From Kiota + + UserRequestBuilder(); + MailRequestBuilder(); +} + +``` + +#### Graph core library specifications + +This library contains the +- Factory method/classes returning the: + - Core client with the user configurations such as authprovider, custom middleware, request options. + - HttpCore instance for the service library with user configurations such as authprovider, custom middleware, request options. + +- Tasks + - PageIteratorTask + - LargeFileUploadTask + - Batching + +- Authentication Providers + - Use the `IAuthenticationProvider` and authentication provider class from the Kiota abstractions. + +- BaseRequest/IBaseRequest + - These classes/interfaces would be dropped as they are rendered redundant by the existence of `RequestInformation` from the Kiota core libraries and provide better support for conversion to native http request objects. + - Existing extensions/features/enrichments to the classes/interfaces would be moved to the `RequestInformation` through the graph core library.(e.g. one can use `BaseRequest` instances to create a batch request, now we would use `RequestInformation` instances) + +- HttpProvider/IHttpProvider + - These classes/interfaces would be dropped as they are rendered redundant by the existence of `IRequestAdapter` from the Kiota core libraries and provide the necessary functionality to perform http requests + +- Response Handler + - Any existing/needed response handlers to now implement the `IResponseHandler` (or equivalent) from kiota core libraries + +#### Graph Service library specifications + +- Discuss about ways to add custom code or custom configurations to the generated `GraphServiceClient` code. +- The custom configurations that can go here are as follows: + - Setting the default for `HttpCore` with a Graph specific `HttpCore` instance. + - Adding multiple constructors to the `GraphServiceClient`. + +#### Graph Middlewares + +- Import middlewares from Kiota core library +- How to add graph specific checks in the middleware. Example: The JS SDK checks if the url is a Graph url or a custom host passed by the user before appending telemetry headers or auth headers. If not, the headers are removed. + +- AuthHandler - none - This avoids having to configure both the middleware and the provider and the authentication provider implementations are available across any http client +- RetryHandler - Kiota core +- RedirectHandler - Kiota core +- CompressionHandler - Kiota core +- CachingHandler - Kiota core +- ChaosHandler - Graph core +#### Use cases + +- Graph core client +```TypeScript +var response = new coreClient.requestURL("/me").get(); +``` + +- Graph service client +``` +var response = new serviceClient.me().get(); +``` + +- Graph service client calling a core functionality + +- The service library should extend the capabilities of the core library, that is, a user using service client should not require to create or use a core client to access any functionality. +``` +var response = new serviceClient.requestURL("/me").get(); // Example : a user of the JS SDK should be able to access GraphServiceClient.api(/me) without initialising the core. +``` + +- Graph core client with a task + +``` +var response = new coreClient.requestURL("/me").get(); + +PageIterator(coreclient, response) +``` + +- Graph service client with a task + +``` +var response = new serviceClient.me().get(); +PageIterator(serviceClient, response) +``` + +- The service library should extend the capabilities of the core library, that is, a user using service client should not require to create or use a core client to access any functionality. +- Some options to achieve this (TBD): + - Maintain a parent abstract class for the core and the service client. + - `GraphServiceClient` extends the `GraphCoreClient`. + +### More questions + +- Does the generated ApiClient have to be tightly coupled with the generated request builders? Should it always be tightly coupled? [MEM] I ask as there could be scenarios where the request builders are not necessary and the client developers just wants the Kiota.Core functionality in the client, and will use client.requestUrl.Get(); + diff --git a/graph-kiota/httpCore.md b/graph-kiota/httpCore.md new file mode 100644 index 0000000..6b665c3 --- /dev/null +++ b/graph-kiota/httpCore.md @@ -0,0 +1,33 @@ +### IHttpCore + +The primary purpose of the IHttpCore interface is to define the core methods to send requests by the client library generated by Kiota.Builder. This interface will be implemented by us (Microsoft Graph SDK team) in the Kiota Core library for each language. The Kiota Core library will be the default set of implementations of the Kiota Abstractions for a specific language. Kiota Core is generic client used with the service library generated by Kiota.Builder. We will need to provide a Microsoft Graph specific implementation of the middleware and serializers to an instance of HttpCore from Kiota Core. The middleware and serializers will come from the Graph.Core library (maybe, from something like a factory or extension, TBD). + +State the requirement with description and example of when to use each of the following IHTTPCore function. +``` +sendAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; +``` + +``` +sendCollectionAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; +``` + +``` +sendPrimitiveAsync(requestInfo: RequestInformation, responseType: "string" | "number" | "boolean" | "Date" | "ReadableStream", responseHandler: ResponseHandler | undefined): Promise; +``` + +``` +sendNoResponseContentAsync(requestInfo: RequestInformation, responseHandler: ResponseHandler | undefined): Promise; +``` + +``` +enableBackingStore(backingStoreFactory?: BackingStoreFactory | undefined): void; +``` + + + +Kiota core implementation + + +``` +constructor(authProvider, parseNodeFactory, serializationWriteFactory, httpClient); +``` diff --git a/graph-kiota/kiota.md b/graph-kiota/kiota.md new file mode 100644 index 0000000..29096c5 --- /dev/null +++ b/graph-kiota/kiota.md @@ -0,0 +1,180 @@ +### What is Kiota? +Learn [Kiota](https://github.com/microsoft/kiota#readme) + +### APIs that can use Kiota +- Any HTTP API with an Open API specification (For generators). Not limited to Microsoft Graph. + +### Kiota libraries + +Common for all languagues: +- Kiota generator: Generates the request builders +The generated code contains the APIClient class and the request builders. + +``` +class APIClient { + httpCore : HttpCore; + + getResourceById(): ResourceRequestBuilder; +} +``` + +Libraries for each language: + +- Kiota abstractions + - This library contains only abstract classes and interfaces which can be implemented to connect the generated request builders with a client library that makes the call to the API, handles serialization and authentication. + [Kiota abstractions dotnet](https://github.com/microsoft/kiota/tree/main/abstractions/dotnet) + [Kiota abstractions java](https://github.com/microsoft/kiota/tree/main/abstractions/java) + [Kiota abstractions typescript](https://github.com/microsoft/kiota/tree/main/abstractions/typescript) + + - Contains the following: + - HttpCore interface + + ``` + interface HttpCore{ + getSerializationWriterFactory(): SerializationWriterFactory; + + sendAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; + sendCollectionAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; + sendPrimitiveAsync(requestInfo: RequestInformation, responseType: "string" | "number" | "boolean" | "Date" | "ReadableStream", responseHandler: ResponseHandler | undefined): Promise; + sendNoResponseContentAsync(requestInfo: RequestInformation, responseHandler: ResponseHandler | undefined): Promise; + enableBackingStore(backingStoreFactory?: BackingStoreFactory | undefined): void; + } + ```` + - Serialization interfaces + - Authentication: `IAuthenticationProvider`, abstract classes- `anonymousAuthenticationProvider` and `BearerTokenAuthneticationProvider` + - Utils + - ResponseHandler interface + - RequestOption interface + - RequestInformation + - HttpMethod Enum + +- Kiota core + - This is generic core client library (functionality or purpose similar to Microsoft Graph core libraries) + [Kiota core dotnet](https://github.com/microsoft/kiota/tree/main/http/dotnet/httpclient) + [Kiota core java](https://github.com/microsoft/kiota/tree/main/http/java/okhttp) + [Kiota core typescript](https://github.com/microsoft/kiota/tree/main/http/typescript/fetch) + - This library contains the following: + - HttpCore class implementing the abstraction HttpCore interface. + - HttpClientbuilder (.NET, Java) or HTTPClient class (TS) (processes and records the middleware chain used while making requests.) + - Middlewares: RetryHandler, Redirect, Compression, Caching, Telemetry + +``` +class HttpCore implements kiota.abstractions.HttpCore { + constructor(authProvider, parseNodeFactory, serializationWriteFactory, httpClient); + + sendAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; + sendCollectionAsync(requestInfo: RequestInformation, type: new() => ModelType, responseHandler: ResponseHandler | undefined): Promise; + sendPrimitiveAsync(requestInfo: RequestInformation, responseType: "string" | "number" | "boolean" | "Date" | "ReadableStream", responseHandler: ResponseHandler | undefined): Promise; + sendNoResponseContentAsync(requestInfo: RequestInformation, responseHandler: ResponseHandler | undefined): Promise; + enableBackingStore(backingStoreFactory?: BackingStoreFactory | undefined): void; +} + +class HttpClient{ + middlewares : Middlewares(); + send() //calls the MiddlewareChain to make a request with the native HttpClient; +} +``` + +Kiota Generated API Client (This will be the GraphServiceClient) + +``` +class APIClient { + + httpCoreInstance : HttpCore + + SampleRequestBuilder(httpCoreInstance); + ExampleRequestBuilder(httpCoreInstance); +} +``` + +- Kiota serializations + - This library contains implementation of the kiota abstractions serialization interfaces + - Currently targets `JSON` format. + - Other formats to consider: + - Multipart payload + - Base64 encoded string + - text/plain + - xml + +- Kiota auth providers + +### Example of how we use the Kiota libraries: + +1. Clone the Kiota repo, build the project and navigate the path containing the `kiota.exe` +2. Generate the request builder using the command: +``` +kiota.exe -d ../msgraph-sdk-powershell/openApiDocs/v1.0/mail.yml --language csharp -o ../somepath -n namespaceprefix +``` +3. The generation should contain the `APIClient` class and request builders. + +5. Create a demo class to test the `APIClient`. + +4. Import the `KiotaCore` library +- [dotnet](https://github.com/microsoft/kiota/blob/main/docs/requiredtools/dotnet.md) +- [TypeScript](https://github.com/microsoft/kiota/blob/main/docs/requiredtools/typescript.md) + +Example: +``` +import { HttpCore } from '@microsoft/kiota-http-fetch'; +``` + +5. Import the serialization library +- [dotnet](https://github.com/microsoft/kiota/packages/826855) +- [TypeScript](https://github.com/microsoft/kiota/packages/827041) + +``` +import {JsonParseNodeFactory, JsonSerializationWriterFactory} from '@microsoft/kiota-serialization-json'; +``` + +Example: + +6. Import the AuthProvider library or implement the IAuthProvider interface to create a custom AuthProvider class. + +Find a suitable Kiota Authentication library in https://github.com/microsoft/kiota/tree/main/authentication/typescript/azure + + +7. Create a RequestAdapter instance: + +``` +var requestAdapter = new FetchRequestAdapter(authProvider, JsonParseNodeFactory, JsonSerializationWriterFactory) +``` + +8. Create a APIClient instance: + +``` +var apiClient = new APIClient(requestAdapter); +var response = await apiClient.users("").get(); +``` + +### Kiota Middlewares + +#### AuthHandler +#### Retry + +``` +Retry-After: http-date +Retry-After: delay-seconds +``` + +#### Redirect + +#### Compression +#### Caching + +#### Telemetry + +- Introduce a callback option so that user can add custom telemetry code. +- Discuss: Why introduce a callback instead user can have a custom middleware chain with telemetry handler implementation? +- Discuss: Should the callback pattern be used for every middleware? + + + + + + + + + + + +