Rapattoni Developer Resources

Authentication

Magic API access is secured via OAuth2; a transaction with our identity server is required to obtain the necessary bearer token. Currently only the Client Credential grant type is supported.
For Client Credential Grant access, the following parameters must be passed in the body of a POST transaction:

  • grant_type: Client Credential access will always use the client_credentials grant type.
  • client_id: An id provided by the Association staff.
  • client_secret: A value provided by the Association staff, associated with the client_id.
  • scope: Provided by the Association staff. This must match a scope that the API recognizes and that is approved for usage by your credentials. It is part of what defines what you can access in the API.

If the transaction is successful, then the response body will be a JSON object containing the access token, the token expiration date, and the token type. The token type will always be “bearer”, and the time till the token expires is set by the association, on a client by client basis, based upon their rules and regulations.

API Transactions

All transactions must include the Authorization header with the value being the client’s current bearer token obtained from the transaction with our identity server.
The Magic API utilizes standard OData URIs and commands (ODatav4).
Responses, unless otherwise specified, will be in the JSON format.
The Service Document is available via a get request against the root URL (http://redacted/odata). By default, this will return in the XML format but can be requested in JSON by passing “application/json” in the Accept header. This document is a standard OData resource listing all top-level entity sets exposed by the service.( ODatav4 10.1)
The Metadata Document is available via a get request against the root URL with “/$metadata” appended (i.e. http://redacted/odata/$metadata). This resource describes the API’s data model; including data types, relationships between entity sets, and available fields (ODatav4 11.1.2). This resource is only available in the XML format.
Entity Set Queries: All Entity Set queries use the default OData format; the root URL is appended with “/EntitySet” (i.e. to query the Offices Entity Set: http://redacted/odata/Offices)
When Querying against Entity Sets, the Magic API Supports most OData 3 query options, functions and operators. The below list are those query options and some of their associated supported functions and operators. Please see the OData 3 specification for further information in regards to these:

  • $expand: allows for the inclusion of entities related to the base entity set queried. The relationships between entity sets can be found in the metadata document. Multiple entities can be included with comma delimiting. If the relationship is further than 1 degree of separation than the full path to the targeted entity must be included. (ODatav4 11.2.4.2
    Examples:
    • Members?$expand=MemberDesignations : this will return Member records and their related MemberDesignations entries. The Metadata will show Members and MemberDesignations are linked via the Member_Number key.
    • Members?$expand=MemberDesignations($expand=Designations): this will return Member records, their related MemberDesignations entries and the related information to describe the Designations. The Members set links to MemberDesignations via the MemberKeyNumeric key and the MemberDesignations set links to Designations on the MemberDesignation key.
  • $select: specify fields to be returned, if not included all fields will be returned. For selecting fields from expanded entity set relationships, the select is included with the expanded item. (ODatav4 11.2.4.2)
    Examples:
    • Members?$select=MemberKeyNumeric,MemberFirstName
    • Members?$expand=MemberDesignations($select=MemberDesignation)&$select=MemberKeyNumeric,MemberFirstName
  • $top: specify the number of entities to return (ODatav4 11.2.5.3)
    • Members?$top=10

 

  • $skip: skip over the first n entities prior to returning data (ODatav4 11.2.5.4)
    Example:
    • Members?$skip=10
  • $orderby: order the results by a specific field’s value; use asc or desc to specify ascending or descending. To order by multiple criteria use comma delimiting(ODatav4 11.2.5.2)
    Examples:
    • Members?$orderby=MemberFirstName asc
    • Members?$orderby=MemberFirstName asc, OfficeName desc

 

  • $count: $count=true specifies that the total count of entities matching the request must be returned along with the results (ODatav4 11.2.5.5)
    Example:
    • Members?$inlinecount=allpages
  • $filter: restrict the returned entities to only those matching the filter criteria (ODatav4 11.2.5.1)
    • Operators
      • eq: Equal
      • ne: Not equal
      • gt: Greater than
      • ge: Greater than or equal
      • lt: Less than
      • le: Less than or equal
      • and: Logical and
      • or: Logical or
      • not: Logical negation, used in conjunction with other functions and operators to create a negative comparison.
      • add: add to modify a numeric field and utilize the result for comparisons.
      • sub: subtract to modify a numeric field and utilize the result for comparisons.
      • mul: multiply to modify a numeric field and utilize the result for comparisons.
      • div: divide to modify a numeric field and utilize the result for comparisons.
      • (): Functions and operators can be nested using parentheses for precedence.
    • Functions
      • contains: string contains, syntax is: contains(FieldName,’string’)
      • endswith: string ends with, syntax is: endswith(FieldName,’string’)
      • startswith: string starts with, syntax is: startswith(FieldName,’string’)
      • substring: string contains, syntax is: substring(FieldName,1) eq 'string'
      • tolower: string to lower casing
      • toupper: string to upper casing
      • trim: trim all leading and trailing white spaces from a string
      • concat: append one string value to another
      • day: return the day component from a DateTimeOffset or Date
      • hour: return the hour component from a DateTimeOffset
      • minute: return the minute component from a DateTimeOffset
      • second: return the second component from a DateTimeOffset
      • month: return the month component from a DateTimeOffset or Date
      • year: return the year component from a DateTimeOffset or Date

Complex Filter Example:
Offices?$filter=(endswith(Office_Name,‘Realty’) and Street_City eq ‘Ventura’) or Salespersons add 5 gt 10             
&: Multiple query options can be included at once, each separated by an “&”
Example: Members?$expand=MemberDesignations&$top=50&$select=Member_Number, MemberDesignations/Designation
odata.nextLink: In some cases, the number of records matching the query parameters is greater than the number of results the server is capable of returning. If so, the results will include an “odata.nextLink” property that contains the exact URL and query needed to obtain the next set of matching results.
Entity Set queries will by default return in JSON.
Single Entity: To return one specific Entity, the format is EntitySet(key). For example, if pulling back member number 100 from the Members entity set, the root URL would be appended with /Members(100).
HTTP Response Codes

Identity Server

Code Text Description

200

OK

Success

400

Bad Request
“error: unsupported_grant_type”

The grant type entered during Authentication is not supported.

400

Bad Request
“error: invalid_grant”

The username or password included were invalid

400

Bad Request
“error: invalid_client”

The client or client secret included were invalid.

500

Internal Server Error

Most likely occurs due to an issue on the server side.

Magic API

Code Text Description

200

OK

Success

400

Bad Request
“The query parameter 'x' is not supported.”

The given query parameter is not valid.

400

Bad Request
"Could not find a property named 'x' on type 'entityset'."

The given property doesn’t exist in the entity set being queried.

401

Unauthorized
“Authorization has been denied for this request.”

The bearer token passed is expired or invalid.

404

Not Found

An invalid resource was targeted

500

Internal Server Error

Most likely occurs due to an issue on the server side.