Skip to content
Sean Reeise edited this page May 31, 2024 · 6 revisions

Macro Wiki

ApiClient is generally used in this wiki to describe any struct that is implementing Api methods for requests. All of these structs have their name end in ApiClient. For instance take UsersApiClient and UsersIdApiClient:

https://github.com/sreeise/graph-rs-sdk/blob/master/src/users/request.rs

api_client!(UsersApiClient, UsersIdApiClient, ResourceIdentity::Users);

Http Macros

The http macros are implemented using a combination of fields with some variable length argument magic and some specific identifier fields. All http macros and the code that builds the request components can be found here: https://github.com/sreeise/graph-rs-sdk/tree/master/src/client/api_macros

get!(
    doc: "List users",
    name: list_user,
    path: "/users"
);

post!(
    doc: "Invoke action getAvailableExtensionProperties",
    name: get_available_extension_properties,
    path: "/users/getAvailableExtensionProperties",
    body: true
);

get!(
    doc: "Get agreementAcceptances from users",
    name: get_agreement_acceptances,
    path: "/users/{{RID}}/agreementAcceptances/{{id}}",
    params: agreement_acceptance_id
);
  • doc: Description of API that this method calls shown as a doc comment on the method itself. These descriptions are taken directly from the OpenApi configs.
  • name: The name of the method.
  • path: The url path for the api that this method calls without the v1 or beta specific path parts. The macro may only include part of the path for this Api and the full path is built once the request path has been fully determined. This happens when you call the final method in the chaining process of the client such as client.me().get_user(). The chain was .me().get_user() and the final method is get_user().
  • body: The only time body is included in the macro is when the api request requires a body. There is no body: false in the current maturation of the macros. The body: true is just an identifier to tell the code generation that it should also include a parameter for the body when generating this method.
  • params: The URL path parameters listed in order of where they injected into the path. These path parameters are used primarily as a way to show syntax highliting when using this library. The names shown for params is what the names will be for the parameters of the method call. The URL path above has the injection points for {{RID}} and {{id}}. The RID path part is a name used internally to tell the path builder to use the id value stored for the current api client. This value is given to any IdApiClient when they are initialized. For instance when a user id api client is created: client.user("id") - the "id" is stoed in the new UsersIdApiClient struct object created from calling user("id") and this id is what is injected into the path parameter "{{RID}}".

ApiClient Macros

The macro names or naming conventions, if you can call it that, are subject to change.


The api_client_link macro generates a method that will transfer control from one ApiClient to another as well as extend any path parameters onto the url that are currently known.

api_client_link!(calendar_views, CalendarViewApiClient);

The api_client macro generates the struct, fields, methods, and trait impl's for an ApiClient.

api_client!(UsersApiClient, UsersIdApiClient, ResourceIdentity::Users);

The api_client_impl macro is only seen in one place and that is the main Graph client. This macro creates the methods that are the starting point for calling graph apis and in these methods is where the ApiClient's are created using their new method.

api_client_impl!(admin, AdminApiClient);

api_client_impl!(app_catalogs, AppCatalogsApiClient);

api_client_impl!(
   agreement_acceptances, // Method Name
   AgreementAcceptancesApiClient, // ApiClient
   agreement_acceptance, // MethodName
   AgreementAcceptancesIdApiClient // IdApiClient
);