Call endpoint


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:

    Headers
    Key Value Description
    Content-Type application/x-www-form-urlencoded
    OR
    application/json    		 The media type of the resource.
    Authorization Bearer {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’.

    Below is an example of a GET request with the version in the URL as a paramter:

    GET: https://api.mypcorp.com/client/?version=2

    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 clients:

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

    We highly recommend filtering GET requests, using $filter, $select and $top queries, as it greatly reduces the payload size and improves performance. Below is an example of a GET request for a list of clients with an OData query in the URL:

    GET: https://api.mypcorp.com/client/?$filter=ArchiveDate eq null and BusinessNumber eq ‘12345’&$select=ClientGuid, BusinessName&$top=5

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

    Parameters
    Key Example Value Example Description
    $filter ArchiveDate eq null Return only entities that are not archived.
    $select ClientGuid, BusinessName Return a response with only the ClientGuid and BusinessName fields.
    $top 5 Only return a maximum of 5 entities.
    $skip 300 Skip the first 300 entities.
    $count true Show the number of entities there are.
    $orderby CreationDate desc Order by the creation date in descending order.
    $expand KeyContact Return a nested object called KeyContact.

    NB: Nested objects are not included in the response by default. To include nested objects, add the query $expand in the request.

    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

    Send post request

    To send a POST request to MYP API, set the body to raw string and the Content-Type header to application/json.

    A list of entities can be sent with one POST request. For more details on which fields can be sent, refer to the specific endpoint documentation.

    Some endpoints, for example Document, require different instructions for sending a POST request which can be found in the pages for those endpoints.

    NB: If there are any errors or warnings, they will be listed for each entity as a list of strings.

    Here is an example of the response that is returned after the POST request is sent:

    {
  "Responses": [
    {
      "StatusCode": "201",
      "Errors": [],
      "Warnings": [],
      "Value":
      {
        "{ExampleFieldName}": "{ExampleValue}"
      }
    },
    {
      "StatusCode": "201",
      "Errors": [],
      "Warnings": [],
      "Value":
      {
        "{ExampleFieldName}": "{ExampleValue}"
      }
    }
  ]
}

    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