Forum Topic - FRCAPI Notes on the release candidate: (3 Items)
   
FRCAPI Notes on the release candidate  
Here are some things I noticed reading through the documentation for the release candidate:

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
"?
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
Award Listings
    awardId: type? range?
    eventType: what are the options?
    forPerson: Should be boolean? Example shows as "345678" which doesn't make any sense
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
Event Rankings
    wins/losses/ties: Example shows as 0, might want to document as such rather than as "not active"
Event Schedule
    tournamentLevel: Example shows "level", and "Playoff" rather than "qual" or "playoff".
Hybrid Schedule
    tournamentLevel: Same comment as event schedule
    Example shows a surrogate during a playoff match
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
Team Listings
    districtCode: should be null in json example, not empty string
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.
Re: FRCAPI Notes on the 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?

Event Awards/person:

The "null or empty" that I was referring to is at the end of the description paragraph.  It seems like it should say 
something like "null or filled".  Also, why does the XML listing show "i:blah" in instead of "<thing/>" the way some 
other things are like districtCode in the event listings?

Event Awards/teamNumber:

Under "team" the description says that it's optional and the details column does as well.  However, the entries for 
season and eventCode only list required in the details column.  Additionally, things that are optional in other tables 
don't list this fact twice.  For example in Event Listings "districtCode" is optional but this is noted only in the 
details column not the description column.