Difference between revisions of "API Get Info"

From zFairs Contest Management
(Document full response shape for /api/data/info from current API)
Line 1: Line 1:
−
== Get Info==
+
== Get Info ==
−
Some of our api calls will require you to have additional information such as category ids or judging session ids. This api call will provide that information. The results of this api call will grow as our api expands.  
+
Returns lookup data needed by other API calls: categories, subcategories, judging sessions, awards, paperwork file types, rounds, project custom questions, and entry types. Call this first when integrating.
  
 +
=== 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>
 +
 +
 +
=== Request ===
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/info', {
 
fetch('/api/data/info', {
 
     method:'POST',
 
     method:'POST',
Line 9: Line 41:
 
     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', // value of f in your URL
 
             Body: {}
 
             Body: {}
 
         })
 
         })
Line 16: Line 48:
 
.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>
  
−
This will return an object like so
+
=== Response ===
−
 
+
On success <code>Body</code> looks like:
−
<syntaxhighlight lang="JavaScript" line>
 
  
 +
<syntaxhighlight lang="JavaScript">
 
{
 
{
−
Categories : [{
+
  Success: true,
−
Id: 123,
+
  Message: null,
−
Name: "math",
+
  Body: {
−
Abbreviation: "ma"
+
    Categories: [{ Id: 123, Name: "Biology", Abbreviation: "BIO" }],
−
}, ...],
+
    SubCategories: [{ Id: 456, Name: "Microbiology", Abbreviation: "MB" }],
−
SubCategories : [{
+
    JudgingSessions: [{
−
Id: 123,
+
      Id: 1,
−
Name: "hard math",
+
      Name: "Morning Session",
−
Abbreviation: "hm"
+
      MinGrade: 6,
−
}, ...],
+
      MaxGrade: 12,
−
JudgingSessions: [{
+
      StartTime: "...",
−
Id: 123,
+
      EndTime: "..."
−
Name: "early morning",
+
    }],
−
MinGrade: "6",
+
    SpecialAwards: [{ Id: 10, Name: "Best in Fair" }],
−
MaxGrade: "12",
+
    CategoryAward: [{ Id: 3, Name: "1st Place" }],
−
StartTime: "",
+
    PaperworkFileTypes: [{ Id: 7, Name: "Form 1C" }],
−
EndTime: "",
+
    Rounds: [{ Id: 2, Name: "Round One" }],
−
}, ...],
+
    ProjectCustomQuestions: [{
−
SpecialAwards: [{
+
      Id: 55,
−
Id: 123,
+
      Name: "How large is your display?",
−
Name: "big winner",
+
      Values: ["small", "large"] // only when the question has preset values
−
}, ...],
+
    }],
−
CategoryAward: [{
+
    EntryTypes: [{
−
Id: 123,
+
      Id: 1,
−
Name: "first place",
+
      PublicId: "9df61f13-474b-442f-ac1f-edca7348ef71",
−
}, ...],
+
      Name: "Research Entry"
−
PaperworkFileTypes: [{
+
    }]
−
Id: 123,
+
  }
−
Name: "form 1c",
 
−
}, ...],
 
−
Rounds: [{
 
−
Id: 123,
 
−
Name: "Round One",
 
−
}, ...],
 
−
ProjectCustomQuestions: [{
 
−
Id: 123,
 
−
Name: "How big is your project",
 
−
Values : ["small","large"] // this is only populated if the question has preset values.
 
−
}, ...],
 
−
EntryTypes: [{
 
−
Id: 123,
 
−
PublicId: "9df61f13-474b-442f-ac1f-edca7348ef71",
 
−
Name: "Research Entry"
 
−
}]
 
 
}
 
}
 +
</syntaxhighlight>
 +
  
 +
=== Field notes ===
 +
* Use category / subcategory / entry type / award / round / paperwork type ids from this response in other API calls.
 +
* <code>ProjectCustomQuestions.Values</code> is only populated when the question has a fixed list of options.
 +
* <code>PaperworkFileTypes</code> ids are used when uploading paperwork via [[API Upload Project Assets]].
  
−
</syntaxhighlight>
 
  
 +
=== Related APIs ===
 +
* [[API Get Projects]] / [[API Add Project]] / [[API Update Project]]
 +
* [[API Upload Project Assets]]
 +
* [[API Add Category]] / [[API Add Round]]
 +
* [[API Judging Scores]] / [[API Set Judging Assignments]]
  
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Revision as of 12:49, 25 July 2026

Get Info

Returns lookup data needed by other API calls: categories, subcategories, judging sessions, awards, paperwork file types, rounds, project custom questions, and entry types. Call this first when integrating.

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
}


Request

fetch('/api/data/info', {
    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: {}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success Body looks like: 

{
  Success: true,
  Message: null,
  Body: {
    Categories: [{ Id: 123, Name: "Biology", Abbreviation: "BIO" }],
    SubCategories: [{ Id: 456, Name: "Microbiology", Abbreviation: "MB" }],
    JudgingSessions: [{
      Id: 1,
      Name: "Morning Session",
      MinGrade: 6,
      MaxGrade: 12,
      StartTime: "...",
      EndTime: "..."
    }],
    SpecialAwards: [{ Id: 10, Name: "Best in Fair" }],
    CategoryAward: [{ Id: 3, Name: "1st Place" }],
    PaperworkFileTypes: [{ Id: 7, Name: "Form 1C" }],
    Rounds: [{ Id: 2, Name: "Round One" }],
    ProjectCustomQuestions: [{
      Id: 55,
      Name: "How large is your display?",
      Values: ["small", "large"]  // only when the question has preset values
    }],
    EntryTypes: [{
      Id: 1,
      PublicId: "9df61f13-474b-442f-ac1f-edca7348ef71",
      Name: "Research Entry"
    }]
  }
}


Field notes

  • Use category / subcategory / entry type / award / round / paperwork type ids from this response in other API calls.
  • ProjectCustomQuestions.Values is only populated when the question has a fixed list of options.
  • PaperworkFileTypes ids are used when uploading paperwork via API Upload Project Assets.


Related APIs




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