Understanding API Basics

What is an API Endpoint?

Think of an endpoint as a specific web address (URL) where you can send requests to interact with our system.

For example, to get domain information, you might use: https://api.nerve.io/v1/domains

But to make a request, you have to include headers.

What are Headers?

Headers are special instructions you attach to your request.

They contain important information such as your authentication details and the type of data you’re sending or expecting to receive.

Making Your First API Request

Here’s a simple example using cURL, a common tool for making API requests:

curl -X GET "https://nerve.io/api/v1/domains" \
  -H "X-Nerve-Access-Key: your_access_key" \
  -H "X-Nerve-Password: your_password"

Let’s break down what each part means:

• curl: The command-line tool we’re using
• -X GET: Specifies that this is a GET request (reading data)
• -H: Adds a header to the request
• "X-Nerve-Access-Key: your_access_key": Your authentication credentials
• "X-Nerve-Password: your_password": Your access key password

Understanding API Responses

When you make an API request, the server sends back a response. This response contains the information you requested, or tells you if something went wrong.

Different endpoints return different types of information – some might give you a list of domains, others might return DNS records, and so on.

Here’s what a successful response looks like for the https://api.nerve.io/v1/domains endpoint:

{
  "result": [
    "demo.org",
    "example.com",
    "test.com"
  ]
}

This response tells you that your request was successful and returns a list of domains you have access to.

The structure of responses varies depending on what you’re asking for – a DNS records request would return different information, and a domain transfer request would return yet another format.

Authentication Response Codes

Every API response includes a status code – a three-digit number that tells you whether your request was successful or if something went wrong. These codes are like a quick summary of what happened with your request.

You can find the status code in a few places:

• In the HTTP response headers – When you make a request, the server sends back headers that include the status code
• In your programming language – Most programming languages and tools (like cURL) will show you the status code
• In the response body – Sometimes the API will include the status code in the JSON response itself

Think of status codes like traffic lights: green means go (success), yellow means caution (something needs attention), and red means stop (error).

For example, if you get a 401 error, it means your authentication failed. The server might send back a response like this:

{
  "error": "INVALID_KEY",
  "message": "The provided access key is not valid or has expired.",
  "timestamp": "2024-01-15T10:30:00Z"
}

This error response tells you exactly what went wrong – in this case, your access key is either invalid or has expired. The status code (401) gives you the quick summary, while the response body gives you the detailed explanation.

Security Best Practices

{
  "success": true,
  "result": [
    {
      "id": "12345",
      "host": "www",
      "type": "A",
      "answer": "192.168.1.1",
      "ttl": 300
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_abc123def456"
}

{
  "error": "RATE_LIMIT",
  "message": "Too many requests. Please wait and try again.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_abc123def456"
}

{
  "error": "INVALID_KEY",
  "message": "The provided access key is not valid or has expired.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_abc123def456"
}

{
  "error": "REGISTRAR_ERROR",
  "message": "Unable to connect to registrar service.",
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_abc123def456"
}