Search code examples
restapimicrosoft-graph-apiapi-design

Why is the Microsoft Graph API using $ref in the URI?

I have noticed that the Microsoft Graph API is very often using $ref in the URIs.

For example a member can be added to an Office 365 Group using the following HTTP request:

POST /groups/{id}/members/$ref

Why is the $ref suffix used? Does this provide any value or advantage? Does this have some special meaning in this case?

Solution

  • Microsoft is implementing OData. Section 4.4 Addressing References between Entities explains $ref:

    OData services are based on a data model that supports relationships as first class constructs. For example, an OData service could expose a collection of Products entities each of which are related to a Category entity.

    References between entities are addressable in OData just like entities themselves are (as described above) by appending a navigation property name followed by /$ref to the entity URL.