API Get Info: 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
 
(5 intermediate revisions by 3 users not shown)
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.
|-
| <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/info', {
fetch('/api/data/info', {
     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: {}
         })
         })
Line 17: Line 45:
.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 <code>Body</code> looks like:
<syntaxhighlight lang="JavaScript">
{
  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"
    }]
  }
}
</syntaxhighlight>
</syntaxhighlight>


This will return an object like so


<syntaxhighlight lang="JavaScript" line>
=== 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]].
 


{
=== Related APIs ===
Categories : [{
* [[API Get Projects]] / [[API Add Project]] / [[API Update Project]]
Id: 123,
* [[API Upload Project Assets]]
Name: "math",
* [[API Add Category]] / [[API Add Round]]
Abbreviation: "ma"
* [[API Judging Scores]] / [[API Set Judging Assignments]]
}, ...],
SubCategories : [{
Id: 123,
Name: "hard math",
Abbreviation: "hm"
}, ...],
JudgingSessions: [{
Id: 123,
Name: "early morning",
MinGrade: "6",
MaxGrade: "12",
StartTime: "",
EndTime: "",
}, ...],
SpecialAwards: [{
Id: 123,
Name: "big winner",
}, ...],
CategoryAward: [{
Id: 123,
Name: "first place",
}, ...],
PaperworkFileTypes: [{
Id: 123,
Name: "form 1c",
}, ...]
Rounds: [{
Id: 123,
Name: "Round One",
}, ...]
}




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

Latest revision as of 11:55, 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.
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/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.





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