Friendship

Returns information about Friendships between MapMyFitness Users, and allows creation and approval of Friendship requests.

Resource URIs

Item URI: /v7.1/friendship/<friendship_id>/

Collection URI: /v7.1/friendship/

Item

Item methods

The ID used in the href for item requests takes the form <from_user ID>_<to_user ID>.

GET See details of a Friendship between two MapMyFitness users.

PUT Used to modify the status of a pending Friendship request to change it from pending to active. The requesting user must be the to_user on the pending request or an authorization error will result.

DELETE Denies a pending friend request, or deletes an existing active Friendship.

PATCH Used in a manner similar to PUT but does not require re-sending the entire resource representation (just the status field).

Item properties

Name Description Type Required
status pending or active, denoting whether the Friendship has been unilaterally requested or bilaterally confirmed, respectively text Yes
created_datetime The time the pending Friendship was created, or the time it was confirmed and changed to active status. This property is read-only DateTime Yes
message For a pending-status request, the message that the requesting user wishes to pass to the requested user. This property should be provided when POSTing a new resource, but is read-only after the initial Friendship request creation text Yes

from_user Link to the from user of the Friendship. For pending Friendships the is the user that initiated the Friendship request.

to_user Link to the to user of the Friendship. For pending Friendships this is the user that is receiving the Friendship request.

Collection

Collection methods

GET Allows seeing a list of a MapMyFitness user’s friends. POST Used to create a new Friendship request (i.e., a Friendship with status pending) from the requesting user to another MapMyFitness user. The requesting user must be the one specified as the from_user or an authorization error will result.

Collection query parameters

Name Description Type Required
from_user One of this or to_user is required. Limits the results to the user’s active Friendships, or pending Friendships initiated by the specified user. May be the user resource href or the user ID text Yes
to_user One of this or from_user is required. Limits the results to the user’s active Friendships, or pending Friendships requests sent to the specified user. May be the user resource href or the user ID. Useful for finding all pending Friendship requests that have been sent to the to_user by others text Yes
status Limits results to those with the status specified. Valid values are pending (indicating a Friendship request not yet confirmed) or active text No
order_by Order Friendships by specified attributes. Possible values are status,to_user_first_last_name and status,from_user_first_last_name. The default order is by status and then creation date from newest to oldest. text No

Collection properties

Name Description Type HTTP Support  
total_count the total number of Friendships matching the from_user or to_user filter specified int units, should be SI GET: required, POST: required

self A link to this resource

Embedded collections

friendships A collection of Friendships with properties as described under Item properties and links as described under Item links

Usage

GET Friendship entity

Request GET: /v7.1/friendship/{friendship_id}/
Response
{
    "status": "pending",
    "created_datetime": "2014-11-07T22:03:01.437704+00:00",
    "message": "",
    "_links": {
        "to_user": [{
            "href": "\/v7.1\/user\/{to_user ID}\/",
            "id": "{to_user ID}"
        }],
        "self": [{
            "href": "\/v7.1\/friendship\/{from_user ID}_{to_user ID}\/",
            "id": "{from_user ID}_{to_user ID}"
        }],
        "documentation": [{
            "href": "https:\/\/developer.mapmyfitness.com\/docs\/Friendship"
        }],
        "from_user": [{
            "href": "\/v7.1\/user\/{from_user ID}\/",
            "id": "{from_user ID}"
        }]
    }
}

PUT Friendship entity

Request PUT: /v7.1/friendship/{pk}/
{
   "status":"active",
   "_links":{
      "from_user":[
         {
            "href":"/v7.1/user/{from_user ID}/",
            "id":"{from_user ID}"
         }
      ],
      "to_user":[
         {
            "href":"/v7.1/user/{to_user ID}/",
            "id":"{to_user ID}"
         }
      ]
   }
}
Response
{
    "status": "active",
    "created_datetime": "2014-11-07T21:53:36.094201+00:00",
    "message": "",
    "_links": {
        "to_user": [{
            "href": "\/v7.1\/user\/{to_user ID}\/",
            "id": "{to_user ID}"
        }],
        "self": [{
            "href": "\/v7.1\/friendship\/{from_user ID}_{to_user ID}\/",
            "id": "{from_user ID}_{to_user ID}"
        }],
        "documentation": [{
            "href": "https:\/\/developer.mapmyfitness.com\/docs\/v71_Friendship/"
        }],
        "from_user": [{
            "href": "\/v7.1\/user\/{from_user ID}\/",
            "id": "{from_user ID}"
        }]
    }
}

DELETE Friendship entity

Request DELETE: /v7.1/friendship/{pk}/
Response
204 No Content

PATCH Friendship entity

Request PATCH: /v7.1/friendship/{pk}/
{
   "status":"pending",
   "_links":{
      "from_user":[
         {
            "href":"/v7.1/user/{from_user ID}/",
            "id":"{from_user ID}"
         }
      ],
      "to_user":[
         {
            "href":"/v7.1/user/{to_user ID}/",
            "id":"{to_user ID}"
         }
      ]
   }
}
Response
{
    "status": "pending",
    "created_datetime": "2014-11-07T21:53:36.094201+00:00",
    "message": "",
    "_links": {
        "to_user": [{
            "href": "\/v7.1\/user\/{to_user ID}\/",
            "id": "{to_user ID}"
        }],
        "self": [{
            "href": "\/v7.1\/friendship\/{from_user ID}_{to_user ID}\/",
            "id": "{from_user ID}_{to_user ID}"
        }],
        "documentation": [{
            "href": "https:\/\/developer.mapmyfitness.com\/docs\/Friendship"
        }],
        "from_user": [{
            "href": "\/v7.1\/user\/{from_user ID}\/",
            "id": "{from_user ID}"
        }]
    }
}

GET Friendship pending requests collection

Request GET: /v7.1/friendship/?status=pending&to_user={User ID}
Response
{
    "_links": {
        "self": [{
            "href": "\/v7.1\/friendship\/?status=pending&to_user={User ID}&limit=20&offset=0"
        }],
        "documentation": [{
            "href": "https:\/\/developer.mapmyfitness.com\/docs\/Friendship"
        }]
    },
    "_embedded": {
        "friendships": [{
            "status": "pending",
            "created_datetime": "2014-11-07T21:20:39+00:00",
            "message": "Hi, person-I-want-to-friend. Let's be friends.",
            "_links": {
                "to_user": [{
                    "href": "\/v7.1\/user\/{User ID}\/",
                    "id": "{User ID}"
                }],
                "self": [{
                    "href": "\/v7.1\/friendship\/{Friend ID}_{User ID}\/",
                    "id": "{Friend ID}_{User ID}"
                }],
                "from_user": [{
                    "href": "\/v7.1\/user\/{Friend ID}\/",
                    "id": "{Friend ID}"
                }]
            }
        }]
    },
    "total_count": 1
}

POST Friendship collection

Request POST: /v7.1/friendship/
{
    "_links": {
        "to_user": [
            {
                "href": "/v7.1/user/:to_user:/",
                "id": ":to_user:"
            }
        ],
        "from_user": [
            {
                "href": "/v7.1/user/:from_user:/",
                "id": ":from_user:"
            }
        ]
    }
}
Response
{
    "status": "pending",
    "created_datetime": "2014-11-07T22:03:01.437704+00:00",
    "message": "",
    "_links": {
        "to_user": [{
            "href": "\/v7.1\/user\/{to_user ID}\/",
            "id": "{to_user ID}"
        }],
        "self": [{
            "href": "\/v7.1\/friendship\/{from_user ID}_{to_user ID}\/",
            "id": "{from_user ID}_{to_user ID}"
        }],
        "documentation": [{
            "href": "https:\/\/developer.mapmyfitness.com\/docs\/Friendship"
        }],
        "from_user": [{
            "href": "\/v7.1\/user\/{from_user ID}\/",
            "id": "{from_user ID}"
        }]
    }
}

PATCH to create multiple Friendship entities

Request PATCH: /v7.1/friendship/
{
  "friendships": [
        {
            "from_user": "/v7.0/user/37698697/",
            "to_user": "/v7.0/user/43288455/"
        },
        {
            "from_user": "/v7.0/user/37698697/",
            "to_user": "/v7.0/user/42976235/"
        }
  ]
}
Response
{
    "friendships": [
        {
            "status": "pending",
            "created_datetime": "2014-12-12T00:56:53.866393+00:00",
            "from_user": "/v7.0/user/37698697/",
            "to_user": "/v7.0/user/43288455/",
            "message": "",
            "resource_uri": "/v7.1/friendship/37698697_43288455/"
        }
        {
            "status": "pending",
            "created_datetime": "2014-12-12T00:56:53.866393+00:00",
            "from_user": "/v7.0/user/37698697/",
            "to_user": "/v7.0/user/42976235/",
            "message": "",
            "resource_uri": "/v7.1/friendship/37698697_42976235/"
        }
    ]
}