Getting Started with the Ice Cream Calculator REST API

Introduction

The Ice Cream Calculator REST API allows you to access your recipes and ingredients programmatically. This opens up powerful possibilities for automation, custom integrations, and building your own tools on top of Ice Cream Calculator.

What you can do with the API:

• Retrieve your recipe collection
• Access detailed recipe information and calculations
• Browse your ingredient library
• Build custom tools and integrations
• Automate recipe management workflows
• More endpoints coming…

Prerequisites:

• An Premium Ice Cream Calculator account
• Basic understanding of REST APIs (or willingness to learn!)
• A tool to make HTTP requests (curl, Postman, or any programming language)

---

Step 1: Generate Your API Key

Your API key is like a password that lets external applications access your data securely.

How to Create an API Key

1. Log in to your Ice Cream Calculator account
2. Navigate to Account Settings
   • Click your profile icon in the top navigation
   • Select “Account” from the dropdown menu
3. Find the API Access section
   • Scroll down to the “API Access” card
4. Click “Generate API Key”
   • A unique API key will be created instantly
   • Your key starts with icc_ followed by 40 random characters

Important Security Notes

💡 Your API key is like your password – treat it with the same level of security!

---

Step 2: Test Your API Connection

Before diving into coding, let’s verify your API key works.

Quick Test from Account Page

1. In the API Access section, click “Test API Connection”
2. The system will make a test request to verify your key works
3. You’ll see a success message showing how many recipes you have

Test with the API Test Page

For a more comprehensive test:

1. In the API Access section, click “API Test Page”
2. You’ll see a full testing interface with all available endpoints
3. Select an endpoint from the dropdown
4. Click “Send Request” to test it
5. View the formatted JSON response

---

Step 3: Make Your First API Request

Let’s make a real API request to get your recipe list.

Using curl (Command Line)

Open your terminal and run:

curl -H "X-API-Key: icc_your_actual_key_here" \
     https://icecreamcalc.com/api/recipes

Replace icc_your_actual_key_here with your actual API key from the Account page!

Understanding the Response

You’ll receive a JSON response that looks like this:

{
  "success": true,
  "count": 5,
  "recipes": [
    {
      "id": 1,
      "name": "Classic Vanilla Ice Cream",
      "info": "Traditional vanilla base",
      "createdDate": "2025-01-15T10:30:00Z",
      "changedDate": "2025-11-08T14:20:00Z",
      "mixWeight": 1000.0,
      "finalWeight": 950.0,
      "ingredients": [...]
    }
  ]
}

Using Python

import requests

api_key = "icc_your_actual_key_here"
headers = {"X-API-Key": api_key}

response = requests.get(
    "https://icecreamcalc.com/api/recipes",
    headers=headers
)

recipes = response.json()
print(f"Found {recipes['count']} recipes")

# Print first recipe name
if recipes['recipes']:
    print(f"First recipe: {recipes['recipes'][0]['name']}")

Using JavaScript

const apiKey = "icc_your_actual_key_here";

fetch("https://icecreamcalc.com/api/recipes", {
  headers: {
    "X-API-Key": apiKey
  }
})
  .then(r => r.json())
  .then(data => {
    console.log(`Found ${data.count} recipes`);
    if (data.recipes.length > 0) {
      console.log(`First recipe: ${data.recipes[0].name}`);
    }
  });

---

Understanding API Authentication

Every API request (except the test endpoint) requires authentication using your API key.

How Authentication Works

1. Include your API key in the request header named X-API-Key
2. The server validates your key and checks your account status
3. If valid, you get access to your data
4. If invalid, you receive a 401 Unauthorized error

Response Code	Meaning	What to Do
200 OK	Success!	Your request worked, use the data returned
401 Unauthorized	Invalid or missing API key	Check your API key is correct and included in the header
403 Forbidden	You don’t have access to this resource	You can only access your own recipes/ingredients
404 Not Found	Resource doesn’t exist	Check the ID is correct and the resource exists
500 Server Error	Something went wrong on our end	Contact support if the error persists

---

What’s Next?

Now that you’ve successfully made your first API request, you’re ready to explore more!

Continue Learning:

• API Reference Documentation – Complete list of all endpoints and their responses
• Use the API Test Page – Experiment with different endpoints and see what data they return
• Build Something Cool – Create custom tools, automation, or integrations

Need Help?

• Check the API Reference Documentation for detailed endpoint information
• Use the API Test Page to troubleshoot issues
• Contact support if you encounter problems

---

Managing Your API Key

View Your API Key

Go to Account → API Access. Click the eye icon to show/hide your key.

Copy Your API Key

Click the copy icon next to your API key to copy it to your clipboard.

Regenerate Your API Key

If your key is compromised or you need a new one:

1. Go to Account → API Access
2. Click “Regenerate API Key”
3. Confirm the action
4. Your old key will stop working immediately
5. Update any applications using the old key

⚠️ Warning: Regenerating your API key will immediately invalidate the old key. Any applications or scripts using the old key will stop working!

Revoke Your API Key

To completely remove API access:

1. Go to Account → API Access
2. Click “Revoke API Key”
3. Confirm the action
4. Your API key will be deleted
5. You can generate a new one anytime

---

Best Practices

Security

• ✅ Store API keys in environment variables, not in your code
• ✅ Use HTTPS for all API requests (required)
• ✅ Regenerate your key if you suspect it’s been compromised
• ❌ Never commit API keys to version control
• ❌ Never expose API keys in client-side JavaScript

Error Handling

• Always check the HTTP status code before processing the response
• Handle network errors gracefully (timeouts, connection issues)
• Parse and display error messages from the API
• Implement retry logic for temporary failures

Performance

• Cache responses when appropriate to reduce API calls
• Use specific endpoints (e.g., /api/recipes/123) rather than fetching all data
• Consider rate limiting in your application (be a good API citizen!)

---

Common Questions

Can I have multiple API keys?

No, currently each account can have one API key. If you need to use the API from multiple applications, use the same key but store it securely in each application’s configuration.

Is there a rate limit?

Currently, there are no rate limits. However, please use the API responsibly. Excessive usage may result in rate limiting in the future.

Can I access other users’ data?

No, your API key only provides access to your own recipes and ingredients. You cannot access data from other accounts. (Future feature on request).

Does the API cost extra?

No! API access is included with your Ice Cream Calculator Premium account at no additional cost. (Subjected to change)

Can I use the API for commercial applications?

Yes, you can use the API to build tools for your own business. However, you cannot resell API access or create services that compete with Ice Cream Calculator.

What data can I access via the API?

Currently, you can:

• List and view your recipes
• Get calculated recipe data (PAC, POD, etc.)
• List and view ingredients (personal + shared ingredients)

Can I create or modify recipes via the API?

Not yet! The current API is read-only. Write capabilities (creating, updating, deleting) may be added in future updates.

---

Troubleshooting

Problem: “401 Unauthorized” Error

Possible causes:

• API key is missing from the request
• API key is incorrect (typo, missing characters)
• API key was revoked or regenerated

Solution:

• Verify you’re including the X-API-Key header
• Copy your API key again from the Account page
• Make sure there are no extra spaces or characters

Problem: “404 Not Found” Error

Possible causes:

• The recipe or ingredient ID doesn’t exist
• Typo in the endpoint URL
• Trying to access a temporary recipe (not available via API)

Solution:

• Verify the ID exists in your account
• Check the endpoint URL for typos
• Use the API Test Page to verify the endpoint works

Problem: Empty Response or Missing Data

Possible causes:

• You don’t have any recipes or ingredients yet
• Filtering excluded all results

Solution:

• Create some recipes in the web app first
• Check the count field in the response

Problem: “Network Error” or Timeout

Possible causes:

• Internet connection issues
• Firewall blocking the request
• CORS issues (if calling from browser JavaScript)

Solution:

• Check your internet connection
• Verify you can access https://icecreamcalc.com in your browser
• For browser apps, make API calls from your server, not client-side

---

Summary

Congratulations! You now know how to:

• ✅ Generate and manage your API key
• ✅ Make authenticated API requests
• ✅ Understand API responses and error codes
• ✅ Use the API Test Page for testing
• ✅ Follow security best practices

Ready to dive deeper? Check out the API Reference Documentation for complete details on all available endpoints.

💡 Pro Tip: Use the API Test Page to explore endpoints and see example responses before writing code. It’s the fastest way to learn what data is available!