API Add Category: Difference between revisions

From zFairs Contest Management
← Older edit

Trent (talk | contribs)

3 user groups
537 edits
No edit summary
Remove username/password API auth; ApiKey only
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Add Category ==
== Add Category ==
You can use our api to add categories 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 project category 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/category', {
fetch('/api/data/category', {
     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: {
Name: "Category Name",
Id: 0,  // 0 for new
NameShort: "Category Abbreviation",
Name: "Biology",
Description: "", //optional
NameShort: "BIO",
Grades: [9,10,11,12], //optional, use 0 for kindergarten. If not set category will be open to all grades
Description: "Life sciences",
Id: 123 //optional, this will cause the category at this id to be updated,
Grades: [6,7,8,9,10,11,12], // optional grade filter
DoNotShowInOnlineJudging: false, //optional
DoNotShowInOnlineJudging: false,
DoNotAllowTeams: false, //optional
DoNotAllowTeams: false,
MaxTeamSize: 3, //optional, by default there is no limit to the size of a team
MaxTeamSize: 3,
EntryTypeId: 2, //optional, this value comes back from the info api call
EntryTypeId: 1  // optional, from Get Info EntryTypes
            }
}
         })
         })
})
})
Line 27: Line 55:
.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 <code>Body</code> is the category with <code>Id</code> set:


== Remove Category ==
<pre>
{
  Success: true,
  Message: null,
  Body: { Id: 12, Name: "Biology", NameShort: "BIO", ... }
}
</pre>


<syntaxhighlight lang="JavaScript" line>


fetch('/api/data/category/remove', {
=== Field notes ===
    method:'POST',
* Use returned <code>Id</code> as <code>CategoryId</code> when adding/updating projects.
    headers:{'Content-Type': 'application/json'},
* <code>Grades</code> is stored as a category grade filter when provided.
    body: JSON.stringify({
* Categories can be listed via [[API Get Info]] → <code>Categories</code>.
            Username:'admin username',
            Password: 'password',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
            Body: {
Id: 123 //optional, this will cause the category at this id to be updated
            }
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});


</syntaxhighlight>


=== Related APIs ===
* [[API Get Info]]
* [[API Add Project]] / [[API Update Project]]




<br/><br/><br/><br/>
<br/><br/>
[[Category: API]]
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Add Category

Creates or updates a project category 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/category', {
    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
				Name: "Biology",
				NameShort: "BIO",
				Description: "Life sciences",
				Grades: [6,7,8,9,10,11,12],  // optional grade filter
				DoNotShowInOnlineJudging: false,
				DoNotAllowTeams: false,
				MaxTeamSize: 3,
				EntryTypeId: 1  // optional, from Get Info EntryTypes
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success Body is the category with Id set: 

{
  Success: true,
  Message: null,
  Body: { Id: 12, Name: "Biology", NameShort: "BIO", ... }
}


Field notes

  • Use returned Id as CategoryId when adding/updating projects.
  • Grades is stored as a category grade filter when provided.
  • Categories can be listed via API Get Info → Categories.





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