What is Graphiti?
graphiti
is a utility for building complex URLs for interacting with
the Microsoft Graph API.
The idea is to have a builder object with an API in the style of an ORM that one can pass down and modify to ones hearts contempt.
The code currently lives in engine2/models/msgraph/graphiti
.
How do I use graphiti
?
graphiti
uses types and recursion for modelling which easily allows
for building long, complicated URLs.
A simple example
Say you want to access all the files in Microsoft OneDrive for a given user.
Let's call this user Bob. Bob's principal username is his email: bob@graph.microsoft.com
(in a Microsoft Graph context).
Building a URL for retrieving all of Bob's files in OneDrive with graphiti
looks like this:
from os2datascanner.engine2.model.msgraph.graphiti.builder import MSGraphURLBuilder
builder = MSGraphURLBuilder() # Instantiate a builder object.
url = builder.v1().users('bob@graph.microsoft.com').files() # Add the v1.0, users and files endpoints.
url_as_string = url.build() # --> https://graph.microsoft.com/v1.0/users/bob@graph.microsoft.com/files
Note that every endpoint function (like .v1()
and .files()
in the example above)
on the builder object returns a new node object allowing you to chain as many nodes
as you like. It essentially acts like an immutable, stack-like data structure.
If you change you mind about a node, the .parent()
method returns a reference to
the previous endpoint. With this operation, you pop off an endpoint of the stack
of URL endpoints, so to speak. Maybe you didn't want Bob's files. You just wanted
information about Bob's profile:
from os2datascanner.engine2.model.msgraph.graphiti.builder import MSGraphURLBuilder
builder = MSGraphURLBuilder() # Instantiate a builder object.
url_to_files = builder.v1().users('bob@graph.microsoft.com').files() # Add the v1.0, users and files endpoints.
url_to_bob = url_to_files.parent() # Remove '/files' --> https://graph.microsoft.com/v1.0/users/bob@graph.microsoft.com
A more complex example with OData Query Parameters
According to the Microsoft Graph Documentation, the Graph API supports system query options that are compatible with the OData v4 query language.
Of course, graphiti
provides some utilities for manipulating these too.
Perhaps, we want to modify to URL to query Bob's OneDrive files with some OData parameters
for getting only the first five files as .xml
.
The ODataQueryBuilder
class is just the thing for this task:
from os2datascanner.engine2.model.msgraph.graphiti.builder import MSGraphURLBuilder
from os2datascanner.engine2.model.msgraph.graphiti.query_parameters import ODataQueryBuilder
builder = MSGraphURLBuilder() # Instantiate a URL builder object.
url = builder.v1().users('bob@graph.microsoft.com').files() # Add the v1.0, users and files endpoints.
odata = ODataQueryBuilder() # Instantiate a OData builder object.
params = odata.top(5).format('xml')
# Below returns 'https://graph.microsoft.com/v1.0/users/bob@graph.microsoft.com/files?$top=5&$format=xml'
url_as_string = params.build(url)
Note that the build()
-method on ODataQueryBuilder
wraps the graph node object, not the other way around.
This is done under the assumption that query parameters are specific to the context of the endpoint,
that a node object carries information about. In other words, not all query parameters are relevant/
interesting for all endpoints.