Difference between revisions of "API Set Judging Assignments"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
== Upload loading Judging Assignments ==
+
== Set Judging Assignments ==
−
You can use our api to upload your judging assignments. 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.  
+
Creates judge-to-project assignments for a judging round. Optionally clears existing assignments for that round first.
  
 +
=== 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>
 +
 +
 +
=== Request ===
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/JudgingAssignments', {
 
fetch('/api/data/JudgingAssignments', {
 
     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', // value of f in your URL
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
 
             Body: {
 
             Body: {
−
RoundId: 123,
+
RoundId: 2,                 // required — from Get Info Rounds
−
Assignments:[{
+
ClearOldAssignments: true,  // default true
−
ProjectKey: 'e381c719-d7fc-471a-b50c-fe51747652e4',
+
ClearOldScores: true,      // accepted on the model; assignments use ClearOldAssignments
−
JudgeId: '674907d1-60db-443b-b3c9-4755564c94a9',
+
Assignments: [
−
At: '2020-12-31 11:30 am', //optional  
+
{
−
},
+
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
−
ClearOldAssignments:false, //(true or false) Optional, default is true
+
JudgeId: "judge-public-guid", // from Get Judges → id
−
...
+
At: "2024-03-15T15:30:00Z"    // optional interview time
 +
}
 
]
 
]
−
            }
+
}
 
         })
 
         })
 
})
 
})
Line 27: Line 56:
 
.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 ===
 +
On success:
 +
 +
<pre>
 +
{
 +
  Success: true,  // false if any assignment lines could not be resolved
 +
  Message: "",    // lists Judge/Project not found lines
 +
  Body: null
 +
}
 +
</pre>
 +
 +
Invalid round example:
 +
 +
<pre>
 +
{
 +
  Success: false,
 +
  Message: "RoundId 99 is not valid; for this fair you have the following rounds. ..."
 +
}
 +
</pre>
 +
 +
 +
=== Field notes ===
 +
* Empty <code>Assignments</code> returns: <code>No assignments to set</code>.
 +
* Unknown judges or projects are skipped and reported in <code>Message</code>.
 +
* <code>Success</code> is true only when the message tape is empty (every line resolved).
 +
* Judge ids are public GUIDs from [[API Get Judges]]; project keys from [[API Get Projects]].
 +
 +
 +
=== Related APIs ===
 +
* [[API Get Judges]] / [[API Get Projects]] / [[API Get Info]]
 +
* [[API Judging Scores]] / [[API Upload Judging Score]]
 +
* [[API Add Round]]
  
−
</syntaxhighlight>
 
  
−
* Note that all all assignments in this round will be cleared, prior to setting these new assignments.
+
<br/><br/>
 +
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Set Judging Assignments

Creates judge-to-project assignments for a judging round. Optionally clears existing assignments for that round first.

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
}


Request

fetch('/api/data/JudgingAssignments', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
            Body: {
				RoundId: 2,                 // required — from Get Info Rounds
				ClearOldAssignments: true,  // default true
				ClearOldScores: true,       // accepted on the model; assignments use ClearOldAssignments
				Assignments: [
					{
						ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
						JudgeId: "judge-public-guid",  // from Get Judges → id
						At: "2024-03-15T15:30:00Z"     // optional interview time
					}
				]
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success: 

{
  Success: true,   // false if any assignment lines could not be resolved
  Message: "",     // lists Judge/Project not found lines
  Body: null
}

Invalid round example: 

{
  Success: false,
  Message: "RoundId 99 is not valid; for this fair you have the following rounds. ..."
}


Field notes

  • Empty Assignments returns: No assignments to set.
  • Unknown judges or projects are skipped and reported in Message.
  • Success is true only when the message tape is empty (every line resolved).
  • Judge ids are public GUIDs from API Get Judges; project keys from API Get Projects.


Related APIs




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