REST API Reference

Introduction

The MyAppAPI REST API follows REST principles and uses standard HTTP methods to create, read, update, and delete resources. Our API is designed to be intuitive, consistent, and developer-friendly, making it easy to integrate with your applications.

This documentation provides a comprehensive reference for all available REST endpoints, request/response formats, authentication methods, and common patterns for efficient API usage. We've included code examples in multiple programming languages to help you quickly implement API integrations.

Base URL & Versioning

All API requests should be made to the following base URL:

Our API is versioned to ensure backward compatibility as we add new features. The current version is v1. When we release new major versions, we'll maintain support for previous versions according to our API lifecycle policy.

Regional Endpoints

For applications requiring data residency or reduced latency, we offer regional API endpoints:

Authentication

MyAppAPI offers multiple authentication methods to secure your API requests. Choose the method that best fits your security requirements and development workflow.

API Keys

The simplest authentication method is using API keys. Include your API key in the HTTP header of every request:

curl -X GET "https://api.myappapi.com/v1/users" \
  -H "X-API-Key: your_api_key_here"

const axios = require('axios');

const response = await axios.get('https://api.myappapi.com/v1/users', {
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});

import requests

headers = {
    'X-API-Key': 'your_api_key_here'
}

response = requests.get('https://api.myappapi.com/v1/users', headers=headers)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.myappapi.com/v1/users"))
    .header("X-API-Key", "your_api_key_here")
    .build();

HttpResponse response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());

OAuth 2.0

For applications requiring more advanced security or user-context operations, we support OAuth 2.0 authentication. Send the bearer token in the Authorization header:

curl -X GET "https://api.myappapi.com/v1/users/me" \
  -H "Authorization: Bearer oauth_token_here"

const axios = require('axios');

const response = await axios.get('https://api.myappapi.com/v1/users/me', {
  headers: {
    'Authorization': 'Bearer oauth_token_here'
  }
});

import requests

headers = {
    'Authorization': 'Bearer oauth_token_here'
}

response = requests.get('https://api.myappapi.com/v1/users/me', headers=headers)

For complete details on implementing OAuth 2.0 authentication, including obtaining tokens and handling refresh flows, see our Authentication Guide.

JWT Authentication

For advanced authentication scenarios, we also support JSON Web Token (JWT) authentication. See our JWT Authentication Guide for implementation details.

Request Format

The MyAppAPI REST API accepts data in JSON format for request bodies. When sending data to the API, use the following guidelines:

HTTP Methods

Our API uses standard HTTP methods to perform operations on resources:

Headers

Include the following headers with your requests:

Request Body Example

When creating or updating resources, include the data in JSON format in the request body:

{
  "name": "New Project",
  "description": "This is a sample project created via API",
  "visibility": "private",
  "settings": {
    "enableNotifications": true,
    "defaultView": "kanban"
  },
  "tags": ["development", "api-test"]
}

curl -X POST "https://api.myappapi.com/v1/projects" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "description": "This is a sample project created via API",
    "visibility": "private",
    "settings": {
      "enableNotifications": true,
      "defaultView": "kanban"
    },
    "tags": ["development", "api-test"]
  }'

Query Parameters

For GET requests, use query parameters to filter, paginate, and sort results:

Response Format

All responses from the MyAppAPI REST API are returned in JSON format. We use consistent response structures across all endpoints to make integration straightforward and predictable.

Successful Responses

Successful responses include an HTTP status code in the 2xx range and a JSON body with the requested data. The exact structure depends on the type of request:

Single Resource Response

{
  "data": {
    "id": "proj_12345",
    "name": "My Project",
    "description": "This is a sample project",
    "visibility": "private",
    "created_at": "2025-05-11T12:34:56.789Z",
    "updated_at": "2025-05-11T12:34:56.789Z",
    "settings": {
      "enableNotifications": true,
      "defaultView": "kanban"
    },
    "tags": ["development", "api-test"]
  },
  "meta": {
    "request_id": "req_abcdef123456"
  }
}

Collection Response

{
  "data": [
    {
      "id": "proj_12345",
      "name": "My Project",
      "description": "This is a sample project",
      "visibility": "private",
      "created_at": "2025-05-11T12:34:56.789Z",
      "updated_at": "2025-05-11T12:34:56.789Z"
    },
    {
      "id": "proj_67890",
      "name": "Another Project",
      "description": "This is another sample project",
      "visibility": "public",
      "created_at": "2025-05-10T10:20:30.456Z",
      "updated_at": "2025-05-10T10:20:30.456Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "has_more": true,
    "request_id": "req_abcdef123456"
  },
  "links": {
    "self": "https://api.myappapi.com/v1/projects?page=1&limit=10",
    "next": "https://api.myappapi.com/v1/projects?page=2&limit=10",
    "prev": null
  }
}

Create or Update Response

Responses for resource creation (POST) or updates (PUT/PATCH) return the created or updated resource:

{
  "data": {
    "id": "proj_12345",
    "name": "Updated Project Name",
    "description": "This project has been updated via API",
    "visibility": "private",
    "created_at": "2025-05-11T12:34:56.789Z",
    "updated_at": "2025-05-11T14:20:30.123Z",
    "settings": {
      "enableNotifications": true,
      "defaultView": "list"
    },
    "tags": ["development", "api-test", "updated"]
  },
  "meta": {
    "request_id": "req_abcdef123456"
  }
}

Delete Response

Successful delete operations return an HTTP 204 No Content status with no response body.

HTTP Status Codes

We use standard HTTP status codes to indicate the success or failure of API requests:

Rate Limits

To ensure fair usage and maintain service stability, we implement rate limits on API requests. Rate limits vary based on your subscription plan:

When you exceed your rate limit, you'll receive a 429 Too Many Requests response with information about when you can resume making requests.

Rate Limit Headers

Each API response includes headers to help you track your rate limit usage:

Best Practices for Rate Limits

• Implement exponential backoff for retries when you receive a 429 response
• Use bulk operations where available to reduce the number of API calls
• Monitor your rate limit usage with the provided headers
• Consider upgrading your plan if you consistently hit rate limits

Error Handling

When an error occurs, the API returns an appropriate HTTP status code along with a JSON response body containing error details to help you diagnose and resolve the issue.

Error Response Format

{
  "error": {
    "type": "validation_error",
    "message": "The request was invalid and cannot be processed",
    "code": "invalid_parameters",
    "request_id": "req_abcdef123456",
    "details": [
      {
        "field": "name",
        "message": "Name is required",
        "code": "missing_required_field"
      },
      {
        "field": "visibility",
        "message": "Visibility must be one of: private, team, public",
        "code": "invalid_enum_value"
      }
    ]
  }
}

Common Error Types

Handling Errors

Here's an example of how to handle API errors in your code:

async function createProject(projectData) {
  try {
    const response = await fetch('https://api.myappapi.com/v1/projects', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
      },
      body: JSON.stringify(projectData)
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      // Handle error based on status code and error type
      const error = data.error;
      
      if (error.type === 'validation_error') {
        // Handle validation errors
        console.error('Validation error:', error.details);
        // Highlight form fields with errors
      } else if (error.type === 'rate_limit_exceeded') {
        // Implement exponential backoff and retry
        const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
        const waitTime = resetTime - Math.floor(Date.now() / 1000);
        console.log(`Rate limit exceeded. Retry after ${waitTime} seconds.`);
      } else {
        // Handle other errors
        console.error(`Error ${response.status}: ${error.message}`);
      }
      
      return null;
    }
    
    return data.data;
  } catch (err) {
    console.error('Network or parsing error:', err);
    return null;
  }
}

import requests
import time

def create_project(project_data, api_key):
    try:
        headers = {
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        }
        
        response = requests.post(
            'https://api.myappapi.com/v1/projects',
            headers=headers,
            json=project_data
        )
        
        # Parse the response
        data = response.json()
        
        # Check if the request was successful
        if response.status_code >= 400:
            error = data.get('error', {})
            error_type = error.get('type')
            
            if error_type == 'validation_error':
                # Handle validation errors
                print('Validation errors:')
                for detail in error.get('details', []):
                    print(f"  - {detail.get('field')}: {detail.get('message')}")
            elif error_type == 'rate_limit_exceeded':
                # Implement exponential backoff and retry
                reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
                wait_time = max(0, reset_time - int(time.time()))
                print(f"Rate limit exceeded. Retry after {wait_time} seconds.")
            else:
                # Handle other errors
                print(f"Error {response.status_code}: {error.get('message')}")
            
            return None
        
        return data.get('data')
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return None

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public Project createProject(ProjectRequest projectData, String apiKey) {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();
    
    Gson gson = new Gson();
    String requestBody = gson.toJson(projectData);
    
    try {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.myappapi.com/v1/projects"))
            .header("Content-Type", "application/json")
            .header("X-API-Key", apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();
        
        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        JsonObject jsonResponse = gson.fromJson(response.body(), JsonObject.class);
        
        if (response.statusCode() >= 400) {
            JsonObject error = jsonResponse.getAsJsonObject("error");
            String errorType = error.get("type").getAsString();
            String message = error.get("message").getAsString();
            
            if ("validation_error".equals(errorType)) {
                System.err.println("Validation error: " + message);
                // Process detailed validation errors
                error.getAsJsonArray("details").forEach(detail -> {
                    JsonObject detailObj = detail.getAsJsonObject();
                    System.err.println("  - " + detailObj.get("field").getAsString() + 
                                      ": " + detailObj.get("message").getAsString());
                });
            } else if ("rate_limit_exceeded".equals(errorType)) {
                String resetHeader = response.headers().firstValue("X-RateLimit-Reset").orElse("0");
                long resetTime = Long.parseLong(resetHeader);
                long waitTime = Math.max(0, resetTime - (System.currentTimeMillis() / 1000));
                System.err.println("Rate limit exceeded. Retry after " + waitTime + " seconds.");
            } else {
                System.err.println("Error " + response.statusCode() + ": " + message);
            }
            
            return null;
        }
        
        // Extract and return the project data
        JsonObject data = jsonResponse.getAsJsonObject("data");
        return gson.fromJson(data, Project.class);
    } catch (Exception e) {
        System.err.println("Network or parsing error: " + e.getMessage());
        return null;
    }
}

Pagination

For endpoints that return collections of resources, we provide pagination to allow you to efficiently work with large datasets.

Page-Based Pagination

By default, we use page-based pagination. Use the page and limit query parameters to control the pagination:

Pagination parameters:

The response includes pagination metadata in the meta object and navigation links in the links object:

{
  "data": [ /* Array of resources */ ],
  "meta": {
    "page": 2,
    "limit": 25,
    "total": 142,
    "has_more": true,
    "request_id": "req_abcdef123456"
  },
  "links": {
    "self": "https://api.myappapi.com/v1/projects?page=2&limit=25",
    "next": "https://api.myappapi.com/v1/projects?page=3&limit=25",
    "prev": "https://api.myappapi.com/v1/projects?page=1&limit=25"
  }
}

Cursor-Based Pagination

For large datasets or real-time data, we offer cursor-based pagination. Use the after parameter with the cursor value from the previous response:

The response includes a next_cursor in the metadata:

{
  "data": [ /* Array of resources */ ],
  "meta": {
    "limit": 50,
    "next_cursor": "evt_67890ghijkl",
    "has_more": true,
    "request_id": "req_abcdef123456"
  },
  "links": {
    "self": "https://api.myappapi.com/v1/events?limit=50&after=evt_12345abcdef",
    "next": "https://api.myappapi.com/v1/events?limit=50&after=evt_67890ghijkl"
  }
}

Best Practices for Pagination

• Use the highest practical limit value to reduce the number of API calls
• For real-time data or large datasets, prefer cursor-based pagination
• Use the provided next and prev links for navigation rather than constructing URLs manually
• Check the has_more flag to determine if more results are available

Filtering & Sorting

Many API endpoints support filtering and sorting to help you retrieve exactly the data you need.

Filtering

Use query parameters to filter resources based on their attributes:

Common filter operators:

Sorting

Use the sort parameter to specify the field and direction for sorting results:

You can sort by multiple fields by separating them with commas:

Filtering & Sorting Metadata

The response metadata includes information about the applied filters and sort criteria:

{
  "data": [ /* Array of resources */ ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "has_more": true,
    "filters": {
      "status": "active",
      "visibility": "public",
      "created_after": "2025-01-01T00:00:00Z"
    },
    "sort": ["created_at:desc"],
    "request_id": "req_abcdef123456"
  },
  "links": {
    /* Pagination links */
  }
}

API Resources

The MyAppAPI REST API is organized around resources. Each resource has a set of endpoints for performing operations on that resource. Below is an overview of the primary resources available in our API.

Available Resources

Resource Endpoints Pattern

Each resource follows a consistent endpoint pattern:

Example: Projects Resource

Here's a complete example of the Projects resource endpoints: