|
Re: FRCAPI Notes on the release candidate
|
02/11/2015 3:53 PM
post4250
|
Re: FRCAPI Notes on the release candidate
Thanks for the feedback on the documentation. I've added comments inline with "AH" marking them.
Version numbers:
It says that the version number is at the top of the page, but I'm not certain what it is. Is it "Release Candidate
"?
AH: The version number will be added when it is considered a release (i.e. final). This documentation is still subject
to revision based on feedback like yours, so we called it release candidate.
Event Awards
Wording regarding person field: Should it say "null or empty"?
awardId: What is the range of this? Can I store it in a 32 bit integer?
GET/teamNumber: Extraneous "Optional" in description
AH: I don't understand what you mean by "should it say null or empty" in the first part of your comment. The
documentation mentions that, if the award is for a person, the person's name will be set there.
awardId: The fields that end with "id" are all used for internal reporting at FIRST HQ. We added a note about
recommending they not be used for public applications, since we cannot guarantee what values will show up there. I'm not
sure what you mean by GET/teamNumber?
Award Listings
awardId: type? range?
eventType: what are the options?
forPerson: Should be boolean? Example shows as "345678" which doesn't make any sense
AH: for "awardId" it is the same as above- shouldn't be used for anything public so we don't guarantee certain types of
values. eventType: added notes to documentation about possible returns. forPerson is updated as well.
Match Results
end: It looks like this is inclusive. Consider documenting whether or not it is.
station: description shows "red or blue" but examples show "Red" or "Blue"
tournamentLevel: description says "qual" or "playoff", examples show "Qualification" or "Playoff"
matchNumber/start/end: might want to say not merely number but positive integer
AH: end: added note about inclusive. station: the examples are accurate. tournamentLevel: it is correct as documented.
You have to make your requests with qual/playoff, but the return has a bit of a nicer human-readable format, which ends
up being Qualification or Playoff.
Event Rankings
wins/losses/ties: Example shows as 0, might want to document as such rather than as "not active"
AH: the notes under "response details" outline that win/loss values are not used in 2015. But they will still be
included in the return, since they might be useful in future years if win/loss games return.
Event Schedule
tournamentLevel: Example shows "level", and "Playoff" rather than "qual" or "playoff".
AH: this is the same reasoning as match schedule, the requests are "qual" and "playoff" but the return values will be
more "readable"
Hybrid Schedule
tournamentLevel: Same comment as event schedule
Example shows a surrogate during a playoff match
AH: level: see notes above. And it's true that surrogates don't appear in Playoff matches, but these are just examples
of how a surrogate would appear on the schedule, if they existed.
Event Listings
dateStart/dateEnd: A date and time is given but only the date appears to be meaningful. If the time will not be
filled in consider removing it.
divisionCode json example: should be null not empty string
districtCode json example: should be null not empty string
AH: date/time, only the dates are really useful on event listings, but we are going to leave the full datetime so it can
be more effectively processed by anyone using a library that parses common date/time formats. then, if we do implement
time, or start time matters at a particular event, it is already there. The examples have been updated.
Team Listings
districtCode: should be null in json example, not empty string
AH: examples updated.
|
|
|