Croquet Scores - Import Results

croquet-scores-import-results.md

Croquet Scores - Import Results

Revision Notes

Wednesday, 29 June 2016 23:38 UTC

• Added support for names as "T Murphy"

Tuesday, 28 June 2016 16:13 UTC

• Renamed winner name to player a
• Renamed loser name to player b

Monday, 27 June 2016 20:54 UTC

• Added game id is unique to event.

Monday, 27 June 2016 20:08 UTC

• Added Miscellaneous section.
• Responses.
• Added info for replace-results & add-results endpoints.
• Added info for result format.

Monday, 27 June 2016 08:51 UTC

• Explicity stated when field quotes are required.
• Added Fields (Columns) section.
  • Added game id field.
  • Added status field.
• Added Versioning section.

Goals

Goals for this iteration of the uploading results:

• Quickest and easiest method for Dave M implement
• Quickest and easiest method for Dave M to submit results
• One-way uploading of results.

Miscellaneous

• Blank lines are ignored.
• replace-results endpoints
  • Add and replace results.
  • When game id is new to Croquet Scores the game/match is added.
  • Otherwise the game applies any changes.
• add-results endpoints
  • Only adds new games.
  • When game id exists in Croquet Scores then the response will be HTTP status code 400 and body along lines of 'game-id X exists'

Fields (Columns)

Quotes around field values are only required if the line contains a line-feed (LF) or the field contains a comma.

Each Endpoint documents which fields, and order, are required. This section describes the fields.

• game id.
  • This field must be unique to the event (not tournament) and not change between uploads.
  • The id can be alpha/numeric.
  • Game id will allow Croquet Scores to retain timestamp when game result has not changed since last upload.
• player a.
  • Name can be initial + last name. i.e. T Murphy in upload file with match with Tim Murphy on Croquet Scores. If tournament has Tim Murphy & Tony Murphy then upload data cannot use T Murphy.
• status. beat, lost to or is playing. "is playing" its a BoX match in progress.
• player b.
  • Same rules as player a.
• result.
  • Single games matches will be +26 format, matches are "+26,+26".
  • Note that quotes are required for matches.
  • For this iteration only UK format scores (eg +26tp) are be allowed.
  • Score must start with + or - then any number or digits followed by any peeling info.
  • Digits are not validated to allow flexibility for all disciplines.
  • Peeling info is not validated except (t)
  • When peeling info ends with (t) then score will be recorded as timed out difference. e.g. If result is +4(t) then Croquet Scores will record score as 4 - 0.
• event slug. The slug created by croquet scores for the event.

Endpoints

One of 4 endpoints can be used to HTTP POST results.

Endpoint 1

https://api.croquetscores.com/2016/ac/ca-open-championship/<event-slug>/replace-results

e.g. https://api.croquetscores.com/2016/ac/ca-open-championship/doubles-championship/replace-results

Data Format

"game id","player a","status","player b","result"

e.g. "a","Joe Blow & John Doe","beat","Jane Doe & Jill Pink","+2TP,-24,+26sxp"

Endpoint 2

https://api.croquetscores.com/2016/ac/ca-open-championship/<event-slug>/add-results

e.g. https://api.croquetscores.com/2016/ac/ca-open-championship/doubles-championship/add-results

Data Format

"game id","player a","status","player b","result"

e.g. 1,"Joe Blow & John Doe","beat","Jane Doe & Jill Pink","+2TP,-24,+26sxp"

Endpoint 3

https://api.croquetscores.com/2016/ac/ca-open-championship/replace-results

e.g. https://api.croquetscores.com/2016/ac/ca-open-championship/replace-results

Data Format

"event-slug","game id","player a","status","player b","result"

e.g. "doubles-championship","long id is ok","Joe Blow & John Doe","beat","Jane Doe & Jill Pink","+2TP,-24,+26sxp"

Endpoint 4

https://api.croquetscores.com/2016/ac/ca-open-championship/add-results

e.g. https://api.croquetscores.com/2016/ac/ca-open-championship/add-results

Data Format

"event-slug","game id","player a","status","player b","result"

e.g. "doubles-championship",5,"Joe Blow & John Doe","beat","Jane Doe & Jill Pink","+2TP,-24,+26sxp"

Authentication

HTTP Basic Authentication will be used with users Croquet Scores' user name & password.

Responses

Each endpoint will respond with one the following HTTP status codes.

202 Accepted

The data has been validated and added to the queue for processing.

400 Bad Request

The data has one or more errors. The response body will contain human readable error messages.

401 Unauthorized

Username and password do not match.

404 Not Found

URL does not exist.

405 Method Not Allowed

HTTP POST was not used.

500 Internal Server Error

Croquet Scores threw an exception.

Versioning

If versioning is required in the future then HTTP Headers will likely be used. Alternatively trailing /{version info}.