Difference between revisions of "API Judging Scores"

From zFairs Contest Management
(Document score upload and JudgingScoresForRound get)
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. Prefer this over username/password.
 +
|-
 +
| <code>Username</code> / <code>Password</code> || Yes* || Alternate auth if not using ApiKey.
 +
|-
 +
| <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.
 +
|}
 +
 +
* Provide '''either''' <code>ApiKey</code> '''or''' <code>Username</code>+<code>Password</code>.
 +
 +
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',
Line 9: Line 47:
 
     body: JSON.stringify({
 
     body: JSON.stringify({
 
             ApiKey:'<Private key>',
 
             ApiKey:'<Private key>',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
 
             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 18: Line 57:
 
.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]]

Revision as of 12:49, 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. Prefer this over username/password.
Username / Password Yes* Alternate auth if not using ApiKey.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.
  • Provide either ApiKey or Username+Password.

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=949"