Difference between revisions of "API Add Round"

From zFairs Contest Management
(Created page with "== Add Judging Round == You can use our api to add judging '''Rounds''' to your contest. To do this you need to POST a message to your site. Below is an example of what needs...")
 
(Remove username/password API auth; ApiKey only)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Add Judging Round ==
+
== Add Round ==
−
You can use our api to add judging '''Rounds''' to your contest. To do this you need to POST a message to your site. Below is an example of what needs to be posted.
+
Creates or updates a judging round for the fair.
  
 +
=== 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/round', {
 
fetch('/api/data/round', {
 
     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: {
−
RoundName: "Round Name",
+
Id: 0,              // 0 for new round
−
RoundValue: 100, //0-100
+
RoundName: "Round One", // required
−
IsSubRound: false, // false or true
+
RoundValue: 100,   // optional, default 100
−
Id: 0 //0 to create a new round, or the round Id to update an existing round
+
IsSubround: false   // optional, default false
−
            }
+
}
 
         })
 
         })
 
})
 
})
Line 22: Line 50:
 
.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>
  
−
</syntaxhighlight>
+
=== Response ===
 +
On success:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { Id: 2, RoundName: "Round One", RoundValue: 100, IsSubround: false }
 +
}
 +
</pre>
 +
 
 +
If name is missing:
 +
 
 +
<pre>
 +
{ Success: false, Message: "Round name not set." }
 +
</pre>
 +
 
 +
 
 +
=== Field notes ===
 +
* Round <code>Id</code> is required by judging assignment and score APIs.
 +
* List existing rounds via [[API Get Info]] → <code>Rounds</code>.
 +
 
 +
 
 +
=== Related APIs ===
 +
* [[API Get Info]]
 +
* [[API Set Judging Assignments]]
 +
* [[API Judging Scores]] / [[API Upload Judging Score]]
 +
 
 +
 
 +
<br/><br/>
 +
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Add Round

Creates or updates a judging round for the fair.

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/round', {
    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: {
				Id: 0,              // 0 for new round
				RoundName: "Round One",  // required
				RoundValue: 100,    // optional, default 100
				IsSubround: false   // optional, default false
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success: 

{
  Success: true,
  Message: null,
  Body: { Id: 2, RoundName: "Round One", RoundValue: 100, IsSubround: false }
}

If name is missing: 

{ Success: false, Message: "Round name not set." }


Field notes

  • Round Id is required by judging assignment and score APIs.
  • List existing rounds via API Get Info → Rounds.


Related APIs




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