Follow

Officials REST API Basics

Introduction

The Officials API provides a RESTful interface to interact with many of Arbiter’s website features, including membership, custom fields, registration, testing, and clinic. Both XML and JSON responses are supported for simple integration with almost any programming language. This document provides details for developers on how to integrate with the Officials API.

 

Entry Points

The Officials API provides two separate entry points:

Limitations

The Officials REST API allows a maximum request of up to 500 officials.  If the account you are pulling information from has more than 500 officials, then you will need to query down the results.

Example

https://arbiterrest.arbitersports.com/groups/100000/officials?limit(250,251)

This returns up to 250 officials, beginning with the 251st official in the group (presumably the first 250 have already been retrieved).

Authentication

The Officials API requires a username and password to be provided through HTTP Basic authentication with every request. This username requires API specific rights that must be requested through your Arbiter contact.

Once you have an account with API access, you can begin by sending an HTTP request to the API Entry point listed above. Every request you make must contain an “Authenticate” header with your credentials encoded according to the HTTPBasicauthentication scheme or the service will return a 401 HTTP Status Code with a WWW-Authenticate header. The good news is that the HTTP Basic scheme is easy to implement, and most languages provide built-in support for it. See http://en.wikipedia.org/wiki/Basic_access_authentication for implementation specifics.

Your web browser also supports HTTP Basic, and will prompt for credentials after receiving a 401 response code. This makes it easy to explore the API through your web browser without writing a single line of code.

 

API Requests

The Officials API works through standard HTTP calls, and thus is compatible with almost any programming language. Any modern programming language should be able to make HTTP calls - consult your favorite language’s documentation for specifics.

This also means that you can explore the API through any web browser. You can easily inspect the HTTP headers that your browser sends and receives using a tool like Fiddler, or using the network inspection capabilities of Chrome’s DeveloperTools, Firefox’s Firebugextension, or Internet Explorer 8+’s F12 DeveloperTools.

 

Request URLs

Each resource is identified by a unique URL. A resource can either be a single entity or a collection of entities. Collection resources have paths like “/groups/” and do not end with identifiers. Single entity resources have paths like “/groups/{id}” where {id} is the identifier for a specific entity within that collection.

Collection resources support additional parameters for query control that can be passed through the HTTP request’s query string in a format known as Resource Query Language (RQL). RQL defines a standard format allowing for filtering, sorting, and paging of the collection.

 

Output formats

The Officials API handles multiple output formats. Currently, the API supports XML or JSON output which are both widely supported by most programming languages. Output formats are selected using the “Accept” HTTP request header or appending “accept(format)” to the query string for a given resource.

XML will be used as the default format if nothing is specified. A request to “.../groups/” will return all groups the current user has access to in an XML format. The JSON representation of this same resource can be specified by appending “accept(json)” to the URL to yield “.../groups/?accept(json)”.

 

HTTP Methods

REST APIs expose resources (nouns) using standard HTTP methods (verbs) to denote actions against that resource. Standard CRUD actions are translated as:

  • GET: “Read” the resource at the given URL
  • POST: “Create” a new resource in the given collection URL
  • PUT: “Update” the resource at the given URL
  • DELETE: “Delete” the resource at the given URL

For the first phase of this API, only GET requests are supported. Additional HTTP methods will be added in over time.

 

Collection Paging

All collections support paging using RQL’s “limit(start,count) querystring parameter. For performance reasons, several collections may require paging. A request for 5000 officials records at once will take an exceptionally long time for the service to collect and send across the network. For large collections it is recommended to request and process the collection in smaller “pages”.

Examples:

athttp://arbiterrest.arbitersports.com/groups/12345/officials/?limit(20,20)will contain the first 20 items in the collection. The next 20 items are available at athttp://arbiterrest.arbitersports-beta.com/groups/12345/officials/?limit(20,20), the next with ?limit(40,20) and so on until an empty collection is returned.

 

RQL: Resource Query Language

Based on work by Kris Zyp of Sitepen.com. http://www.sitepen.com/blog/2010/11/02/resource-query-language-a-query-language-for-the-web-nosql/ Only the subset of RQL listed below is supported.

Filtering

Logical Operators

and(query,query,...) | query&query

              Filters for objects where all of the given query operators are true.

and(price=19.00,eq(rating,5))

Also has shorthand syntax using standard & querystring syntax:

price=19.00&rating=5        

 

or(query,query,…) | (query|query)

              Filters for objects where any one of the given operators are true.

                             or(price=19.00,eq(rating,5))

 

              Also has shorthand syntax using | in place of standard querystring “&” syntax:

                             (price=19.00|rating=5)

 

Relational operators

eq(property,value) | property=value

Filters for objects where the specified property's value is equal to the provided value.

eq(price,19.00)

Also has a shorthand syntax follows that follows normal querystring parameter syntax:

              price=19.00

ne(property,value)

              Filters for objects where the specified property is not equal to the provided value

                             ne(rating,0)

gt(property,value) | property>value

              Filters for objects where the specified property is greater than the provided value

                             gt(rating,0)

              Also has shorthand syntax using > in place of standard querystring “=” syntax

                             rating>0

lt(property,value) | property<value

              Filters for objects where the specified property is less than the provided value

                             lt(rating,3)

              Also has shorthand syntax using < in place of standard querystring “=” syntax

                             rating<3

ge(property,value) | property>=value

              Filters for objects where the specified property is greater than or equal to the provided value

                             ge(rating,2)

              Also has shorthand syntax using >= in place of standard querystring “=” syntax

                             rating>=2

le(property,value) | property<=value

              Filters for objects where the specified property is less than or equal to the provided value

                             lt(rating,2)

              Also has shorthand syntax using <= in place of standard querystring “=” syntax

                             rating<=2

in(property,(value,value,...))

Filters for objects where the specified property's value is in the provided array

              in(id,(1,5,6,8,21))

contains(property,(query))

Filters for objects where the specified property is a collection and that collection has items containing the given query.

              contains(phones,(type=Mobile))

             

Sorting

sort([+/-]field)

Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property. To sort by foo in ascending order:

sort(+foo)

One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:

sort(+price,-rating)
 

Paging

limit(count, offset)

Returns a limited range of records from the result set. The first parameter indicates the number of records to return and the second parameter indicates the starting offset (number of items to skip).

limit(10, 30)

Output Formats

accept(format)

Custom extension to RQL that allows for specifying the desired return content type. This overrides the value provided in the HTTP “Accept” header, if any.

                             accept(application/json) or simply accept(json)

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments