 |
Reference: RidgeStar-Rest API |
|
| Get Started |Calendar |Locations |
Sites with the RidgeStar REST (Representational State Transfer) API (Application Programming Interface) active will be capable of interacting with remote Clients (other websites and/or programs at other Internet end-points), as follows:
The API
The API has been built to generally conform to commonly accepted standards associated with RESTful Servers. This is not to say that the API is 100% a REST implementation, but it has made efforts to adhere to the principles and concepts embodied by REST.
The API is built upon a few basic terms that should be clarified from the outset:
- Resource
- Identifies a logical set of information available from the API. In this context, a Resource might refer to a single database table, might be a subset or superset of one or more database tables, or might even be simple meta-data available to describe the available Resources.
- Properties
- Each Resource has one or more Properties that, in turn, have one or more values. Conceptually, when a Resource is the result of a data table, a Property is a data field within the data table and the Property's value is synonymous with the data field value.
Syntax
The API Get has the general form:
{protocol}:// {site} /api {/resource} [.{format}] [/{item} ...] [? {keywords} ] ]
where...
- protocol
- Specifies the connection protocol to be followed. Use "HTTPS" (if TLS certificates are supported by the {site}), otherwise use "HTTP".
- site
- The identity, name, or destination containing the REST Server
- api
- The lower case constant "api" specifies that you desire to contact the Application Program (REST) Interface for the {site}
- resource
- The named "Resource" available from the {site} via the API
- format
- The Type of response expected/preferred. Specify .json (the default if no {format} is specified), .xml, or .html (if desired). The Get Request Accept Header will be honored (application/json, application/xml, or text/html), if provided, but will be overridden by the {format} specified in the URI (if present).
- item
- An optional specific Item within the Resource. Additional {item} specification can be provided, if the Resource offers multiple levels of data available (varies by {site} and Resource).
- keywords
- Provides additional qualifiers to control the contents of the response and can contain....
- criteria
- permits the query to be constructed such that Boolean conditions can be specified. General syntax is
criteria={argument=value [{,|:} ...]] } [{,|:}{argument=value[, ...]} ]
Each {argument and value pair is ORed (,) or ANDed(:) together} which is then ORed (,) or ANDed(:) with the other {...} entries to develop the list of data records that will be returned.The operator to specify the AND condition within individual {...} entities is a colon (:) NOT an ampersand. This is because the ampersand is parsed as an independent HTTP element and, thus, is not a portion of the criteria element the REST Server can utilize. (Note: REST Version 5.3.3 will accept either syntax, but....use the colon, not the ampersand for clarity).
- expand
- Identifies the exact Properties of the Resource that should be "expanded" to an array containing all pertinent Properties of the Item. This is useful to obtain detailed information about a Resource Property that does, itself, also represent a Resource with distinct Properties.
There are specialized grouping values that can be specified to imply expansion to more than one Property in the Resource:
- Positions: requests that all Referee positions be expanded (Ref, AR1, AR2, ... as specified in the {site}
- Dates: requests that all Dates and DateTime defined Properties that are returned be expanded to include additional detail about the Date and Time (TimeZone, etc.)
- limit
- The number of entries to return in the response (default is unspecified or "No limit")
- offset
- The first entry to include in the response (default is 1 or the "first" entry)
- order
- Specified the sequence that sorts the resulting response entries (detault is defined by the {site} Resource definition).
- properties
- Identifies the individual Properties that should be returned (a list of properties is delimited by a comma). The default set of Properties returned for a Resource is defined by the {site}
- Positions
- keywords defined by the Resource can be provided to control which Items in the Resource will be obtained
- {criteria}
- keywords defined by the Resource can be provided to control which Items in the Resource will be obtained. Specifying multiple keywords (e.g. dmaGender=G&dmaLevel=U14) implies a boolean AND between the data elements. Use the criteria keyword itself to specify any desired boolean OR conditions.
Examples
All the following examples can be executed by clicking the desired symbol (for HTML, JSON, or XML) below and are sent to Referees.biz
for processing.
- /officers
- Get a list of all Chapter Officers
- /officers/17
- Get all default Properties for a specific individual
- /matches?dmaClient=LakeView&dmaLevel=U16&dmaDate[from]=2020-11-30
- Retrieve Matches for a specific Client and Level of play between specific Dates
- /matches?dmaLevel=U14,U15
- Retrieve Matches for 2 different Levels of play
- /matches?criteria={dmaLevel=U14},{dmaLeague=NFHS}
- Retrieve Matches for a specific Level of Play OR in a specific League of play
- Sending
- https://www.referees.biz/api/matches.json?criteria={dmaLevel=U14},{dmaLeague=NFHS}
- Request Headers
- rsr-Date: 2024-11-14T09:28:31-08:00Content-Type: application/json;rsr-Powered-By: RidgeStar/6.3.0
- Response Headers
- HTTP_Response: 200Date: Thu, 14 Nov 2024 17:28:31 GMTServer: Apache/2.4.62 (Fedora Linux) OpenSSL/3.2.2X-Powered-By: PHP/8.3.13Expires: Thu, 19 Nov 1981 08:52:00 GMTCache-Control: no-store, no-cache, must-revalidatePragma: no-cachersr-Powered-By: server/6.2.6rsr-Resource: matches total=47, first=1, last=10Access-Control-Allow-Origin: *Access-Control-Expose-Headers: rsr-Powered-By,rsr-ResourceTransfer-Encoding: chunkedContent-Type: application/json; charset=utf-8
- Data returned
- [{"dmaKey":1236,"dmaDate":"2024-01-26","dmaTime":"17:00:00","dmaField":48,"dmaStatus":"Normal","dmaClient":"Quadco","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"JV","dmaDivision":"A","dmaSeason":"Spring","dmaHome":"Timberline","dmaAway":"North Thurston","dmaPositions":{"dmaRef":0,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":16,"dloName":"Regional Athletic Complex","dloAddress":"8341 Steilacoom Rd SE","dloCity":"Lacey","dloState":"WA","dloZip":98503,"dloLongitude":"-122.7557373","dloLatitude":"47.0461188","dfdKey":48,"dfdName":"RAC #1"},{"dmaKey":1235,"dmaDate":"2024-01-26","dmaTime":"19:00:00","dmaField":48,"dmaStatus":"Normal","dmaClient":"Quadco","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"Varsity","dmaDivision":"A","dmaSeason":"Spring","dmaHome":"Timberline","dmaAway":"North Thurston","dmaPositions":{"dmaRef":0,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":16,"dloName":"Regional Athletic Complex","dloAddress":"8341 Steilacoom Rd SE","dloCity":"Lacey","dloState":"WA","dloZip":98503,"dloLongitude":"-122.7557373","dloLatitude":"47.0461188","dfdKey":48,"dfdName":"RAC #1"},{"dmaKey":7,"dmaDate":"2024-02-16","dmaTime":"10:01:00","dmaField":14,"dmaStatus":"Normal","dmaClient":"MYSA","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"JV","dmaDivision":"A","dmaSeason":"Spring","dmaHome":"Soccer Storms","dmaAway":"Tigers","dmaPositions":{"dmaRef":92,"dmaAR1":45,"dmaAR2":0,"dma4th":0},"dloKey":1,"dloName":"Seattle High School","dloAddress":"101 Main St.","dloCity":"Seattle","dloState":"WA","dloZip":98104,"dloLongitude":"-122.3324419","dloLatitude":"47.6000617","dfdKey":14,"dfdName":"Seattle HS2"},{"dmaKey":61,"dmaDate":"2024-02-24","dmaTime":"10:01:00","dmaField":22,"dmaStatus":"Normal","dmaClient":"KIDS","dmaLeague":"WSYL","dmaGender":"M","dmaLevel":"U14","dmaDivision":"2","dmaSeason":null,"dmaHome":"Boys 142","dmaAway":"Needham","dmaPositions":{"dmaRef":15,"dmaAR1":15,"dmaAR2":0,"dma4th":0},"dloKey":3,"dloName":"Bell College","dloAddress":"10501 NE 2nd Street","dloCity":"Bellevue","dloState":"WA","dloZip":98004,"dloLongitude":"-122.2000388","dloLatitude":"47.6120017","dfdKey":22,"dfdName":"BC#3"},{"dmaKey":108,"dmaDate":"2024-04-02","dmaTime":"15:01:00","dmaField":30,"dmaStatus":"Normal","dmaClient":"LakeView","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"JV","dmaDivision":"1","dmaSeason":"Fall","dmaHome":"Woodinville","dmaAway":"Bothell","dmaPositions":{"dmaRef":18,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":8,"dloName":"Forest Park","dloAddress":"3301 Grand Ave","dloCity":"Everett","dloState":"WA","dloZip":98201,"dloLongitude":"-122.2123787","dloLatitude":"47.9736510","dfdKey":30,"dfdName":"Forest Park 3"},{"dmaKey":1234,"dmaDate":"2024-05-23","dmaTime":"17:01:00","dmaField":48,"dmaStatus":"Normal","dmaClient":"Quadco","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"JV","dmaDivision":"A","dmaSeason":"Spring","dmaHome":"Tumwater","dmaAway":"Black Hills","dmaPositions":{"dmaRef":7,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":16,"dloName":"Regional Athletic Complex","dloAddress":"8341 Steilacoom Rd SE","dloCity":"Lacey","dloState":"WA","dloZip":98503,"dloLongitude":"-122.7557373","dloLatitude":"47.0461188","dfdKey":48,"dfdName":"RAC #1"},{"dmaKey":111,"dmaDate":"2024-07-07","dmaTime":"18:45:00","dmaField":22,"dmaStatus":"Normal","dmaClient":null,"dmaLeague":"D2","dmaGender":"B","dmaLevel":"U14","dmaDivision":"1","dmaSeason":"Fall","dmaHome":"Cold Ones","dmaAway":"Swollen Knees","dmaPositions":{"dmaRef":45,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":3,"dloName":"Bell College","dloAddress":"10501 NE 2nd Street","dloCity":"Bellevue","dloState":"WA","dloZip":98004,"dloLongitude":"-122.2000388","dloLatitude":"47.6120017","dfdKey":22,"dfdName":"BC#3"},{"dmaKey":96,"dmaDate":"2024-07-19","dmaTime":"12:15:00","dmaField":33,"dmaStatus":"Normal","dmaClient":"SFSRA","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"JV","dmaDivision":null,"dmaSeason":null,"dmaHome":"strikers","dmaAway":"kickers","dmaPositions":{"dmaRef":0,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":10,"dloName":"Sixty Acres","dloAddress":"11600 154th Place NE","dloCity":"Redmond","dloState":"WA","dloZip":98052,"dloLongitude":"-122.1336082","dloLatitude":"47.7039921","dfdKey":33,"dfdName":"60 Acres#2"},{"dmaKey":1233,"dmaDate":"2024-07-27","dmaTime":"16:00:00","dmaField":48,"dmaStatus":"Normal","dmaClient":"Quadco","dmaLeague":"NFHS","dmaGender":"B","dmaLevel":"Varsity","dmaDivision":"A","dmaSeason":"Spring","dmaHome":"Olympia","dmaAway":"Shelton","dmaPositions":{"dmaRef":0,"dmaAR1":17,"dmaAR2":0,"dma4th":0},"dloKey":16,"dloName":"Regional Athletic Complex","dloAddress":"8341 Steilacoom Rd SE","dloCity":"Lacey","dloState":"WA","dloZip":98503,"dloLongitude":"-122.7557373","dloLatitude":"47.0461188","dfdKey":48,"dfdName":"RAC #1"},{"dmaKey":57,"dmaDate":"2024-08-06","dmaTime":"10:00:00","dmaField":33,"dmaStatus":"Normal","dmaClient":"HSC","dmaLeague":"WSYL","dmaGender":"B","dmaLevel":"U14","dmaDivision":"1","dmaSeason":null,"dmaHome":"anytown","dmaAway":"anycity","dmaPositions":{"dmaRef":0,"dmaAR1":0,"dmaAR2":0,"dma4th":0},"dloKey":10,"dloName":"Sixty Acres","dloAddress":"11600 154th Place NE","dloCity":"Redmond","dloState":"WA","dloZip":98052,"dloLongitude":"-122.1336082","dloLatitude":"47.7039921","dfdKey":33,"dfdName":"60 Acres#2"}]
- /matches/1137?properties=dmaKey,dmaDate,dmaRef
- Get 3 Property values for a specific Match
- /matches/1137?properties=dmaKey,dmaDate,dmaRef&expand=dmaRef,Dates
- Expand data fields to obtain translated values
- /matches?properties=dmaKey,dmaDate,dmaRef,dmaAR1,dmaAR2&dmaPositions=17
- Obtain assignments for a specific Referee
- /matches?dmaLevel=U14&offset=4&limit=2
- Starting with the fourth Match, list only 2
- /doc
- Retrieve information about the API and Site hosting it
- /doc/resources/locations
- Obtain a description of the Get options for the Resource named "locations"
| Copyright © 2024 by RidgeStar/webmaster@ridgestar.com |  |