Difference between revisions of "API Judging Scores"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Judging Scores ==
 
== Judging Scores ==
−
You can use our api to access your judges scores for a given round. To do this you need to POST a message to your site. Below is an example of what needs to be posted. You can get round Id from the get info api call, judge id, and project key are returned when a judge or project is added.
+
Two related endpoints:
  
 +
# '''Upload scores''' — <code>POST /api/data/JudgingScores</code> (also documented at [[API Upload Judging Score]])
 +
# '''Get scores for a round''' — <code>POST /api/data/JudgingScoresForRound</code>
 +
 +
=== Authentication ===
 +
All data API calls are <code>POST</code> (unless noted) with JSON body:
 +
 +
{| class="wikitable"
 +
|-
 +
! Field !! Required !! Description
 +
|-
 +
| <code>ApiKey</code> || Yes || Private API key for your site.
 +
|-
 +
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
 +
|-
 +
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
 +
|}
 +
 +
 +
Calls must be run '''server-side''' — do not expose your API key in a browser.
 +
 +
=== Response envelope ===
 +
Most endpoints return:
 +
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,  // error text when Success is false
 +
  Body: { ... }    // endpoint-specific payload
 +
}
 +
</pre>
 +
 +
 +
=== Upload scores ===
 +
See [[API Upload Judging Score]] for the full request shape (<code>RoundId</code>, <code>ClearOldScores</code>, <code>Assignments</code> with <code>ProjectKey</code>, <code>JudgeId</code>, <code>Score</code>, <code>Notes</code>).
 +
 +
=== Get scores for a round ===
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/JudgingScoresForRound', {
 
fetch('/api/data/JudgingScoresForRound', {
 
     method:'POST',
 
     method:'POST',
 
     headers:{'Content-Type': 'application/json'},
 
     headers:{'Content-Type': 'application/json'},
 
     body: JSON.stringify({
 
     body: JSON.stringify({
−
             Username:'admin username',
+
             ApiKey:'<Private key>',
−
            Password: 'password',
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
 
             Body: {
 
             Body: {
−
RoundId: 1, // see below on how to get round Id
+
RoundId: 2,
−
            }
+
ClearOldScores: false  // WARNING: if true this CLEARS scores before reading
 +
}
 
         })
 
         })
 
})
 
})
Line 19: Line 54:
 
.then(data=>{console.log('Success: ',data);})
 
.then(data=>{console.log('Success: ',data);})
 
.catch((error)=>{console.log('Error: ', error);});
 
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
  
 +
==== Response ====
 +
<syntaxhighlight lang="JavaScript">
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: [{
 +
    ProjectId: "AB-100",
 +
    At: "2024-03-15T10:00:00",  // adjusted to fair timezone
 +
    Score: 95.5,
 +
    Notes: "Strong methodology",
 +
    NoShow: false,
 +
    Rubric: "Main Rubric",
 +
    ScoreBreakdown: [
 +
      { Id: "q1", Name: "Scientific method", Score: "5" }
 +
    ],
 +
    JudgeId: 9001,
 +
    JudgePublicId: "judge-public-guid",
 +
    JudgeName: "Sam Judge"
 +
  }]
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
You can get round info by calling our get info api. [[API Get Info]]
+
=== Field notes ===
−
 
+
* Round ids come from [[API Get Info]] → <code>Rounds</code>.
 +
* On the get endpoint, <code>ClearOldScores: true</code> will clear the round scores before returning results — leave it false unless you intend to wipe scores.
 +
* Score breakdown is only returned when rubric detail data is available for the assessment.
  
 +
=== Related APIs ===
 +
* [[API Upload Judging Score]]
 +
* [[API Set Judging Assignments]]
 +
* [[API Get Judges]] / [[API Get Projects]] / [[API Get Info]]
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Judging Scores

Two related endpoints:

  1. Upload scores — POST /api/data/JudgingScores (also documented at API Upload Judging Score)
  2. Get scores for a round — POST /api/data/JudgingScoresForRound

Authentication

All data API calls are POST (unless noted) with JSON body:

Field Required Description
ApiKey Yes Private API key for your site.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.


Calls must be run server-side — do not expose your API key in a browser.

Response envelope

Most endpoints return: 

{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}


Upload scores

See API Upload Judging Score for the full request shape (RoundId, ClearOldScores, Assignments with ProjectKey, JudgeId, Score, Notes).

Get scores for a round

fetch('/api/data/JudgingScoresForRound', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				RoundId: 2,
				ClearOldScores: false  // WARNING: if true this CLEARS scores before reading
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

{
  Success: true,
  Message: null,
  Body: [{
    ProjectId: "AB-100",
    At: "2024-03-15T10:00:00",  // adjusted to fair timezone
    Score: 95.5,
    Notes: "Strong methodology",
    NoShow: false,
    Rubric: "Main Rubric",
    ScoreBreakdown: [
      { Id: "q1", Name: "Scientific method", Score: "5" }
    ],
    JudgeId: 9001,
    JudgePublicId: "judge-public-guid",
    JudgeName: "Sam Judge"
  }]
}

Field notes

  • Round ids come from API Get Info → Rounds.
  • On the get endpoint, ClearOldScores: true will clear the round scores before returning results — leave it false unless you intend to wipe scores.
  • Score breakdown is only returned when rubric detail data is available for the assessment.

Related APIs



Retrieved from "https://wiki.zFairs.com/index.php?title=API_Judging_Scores&oldid=962"