Table of contents

    After you have successfully authenticated your application, you can send a request to the MYP API using an access token.

    Send API request

    The following table shows the header and body fields that can be included when sending a request for a specific endpoint:

    GET: https://api.mypcorp.com/api/client

    Headers
    Key Value Description
    Content-Type application/x-www-form-urlencoded
    OR
    application/json
    The media type of the resource.
    Authorization {access_token} The access token that has been acquired from MYP authentication server.
    x-mypapi-version 2.0 Version of the MYP API (can be specified here or as a parameter).
    Parameters
    Key Value Description
    version 2.0 Version of the MYP API (can be specified here or in the headers).
    {odata_query} {query_value} Additional OData query.
    Body
    Key Value Description
    {name} {value} Fields and their values for sending a POST or PUT request.

    Sending a POST, PUT or DELETE request is similar to sending a GET request. However, fields and their associated body values must be specified when making a call. For more information on which fields are required to be sent when updating or creating a new entity, refer to a specific endpoint in the side navigation.

    API version

    When making a call to the MYP API, an API version must be specified either in the headers or as a parameter. The name of the custom header for the API version is ‘x-mypapi-version’. The name of the parameter for the API version is ‘version’.

    The MYP API version numbering adheres to the following scheme:

    {major}.{minor}

    • major – this version represents changes that are not backwards compatible, such as deleting or changing a field
    • minor – this version represents changes that are backwards compatible, such as adding a new field
    Supported Versions:
    Version Description
    2.0 Current version

    When calling an MYP API endpoint, the response contains headers with the supported and deprecated versions.

    Filter using OData

    The MYP API uses the .NET OData library, allowing responses to be filtered.

    When requesting a full list of a particular entity, the API response will include a list of 300 entities and a link to get the next 300 entities. Below is an example of a GET request for a list of all clients:

    GET: https://api.mypcorp.com/client

    The following table outlines keys that can be sent to filter the response using OData:

    Parameters
    Key Example Value Description
    $top 1 Only return a maximum of 1 entities.
    $select ClientGuid, BusinessName Return a response with only the ClientGuid and BusinessName fields.
    $expand * Return a response with all nested fields included.
    $filter Country eq Australia Filter for records where country field equals to Australia.
    $skip 300 Skip the first 300 entities.
    $count true If this parameter included and value is true, the response will show the number of entities there are for the specified endpoint.

    For improved performance, it is recommended that you only construct a query that requests the fields and number of entities that are required. For example ‘$select=ClientGuid,BusinessName&$top=1’.

    Further reading on OData

    For more information OData:

    Filter by id

    To get a response that includes more details about an entity, specify the id of the entity in the URL. Below is an example of a GET request for a detailed entity:

    GET: https://api.mypcorp.com/client/client_guid

    Response codes

    Responses from the MYP API are returned with standard HTTP response codes. The following table provides examples of the different response codes that you may receive when calling the API:

    Code Message Description
    200 Request successful An API request returned successfully (usually a sucessful GET return).
    201 Post successful A POST method executed successfully.
    204 Update successful An UPDATE method executed successfully.
    302 Found The resource has been found but has been temporarily moved to a different URI. Clients will typically get this message when they are redirected to another URI during the login process.
    400 Bad request The API does not recognise the request. Ensure that the headers are set correctly.
    401 Unauthorised request The request was not authenticated. Ensure that you have set up your authentication tokens correctly.
    403 Forbidden request The requested item is not allowed.
    404 Item not found The requested item was not found. Ensure that the correct id was entered.
    500 Internal server error There is an error with the MYP API server. Try again.

    For further information about the standard HTTP response codes, refer to the official Mozilla website: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status


    Previous article Next article