Quickstart

Welcome to the API fundamentals section of our developers portal.

Understanding REST APIs

REST (Representational State Transfer), is an architectural style for designing networked applications. It relies on a stateless, client-server, cacheable communications protocol — and in virtually all cases, the HTTP protocol is used. REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client. A resource is identified by URIs (Uniform Resource Identifiers) which are used to fetch a representation of the resource. Through the use of HTTP methods, REST APIs enable you to perform operations on these resources, such as creating, retrieving, updating, or deleting them.

REST HTTP Methods

REST APIs primarily use four HTTP methods to perform operations on resources:

Choosing your client

To make an API request, you need a client — a tool or library that sends the request to the API server. There are several options available:

• Command Line Tools: cURL is a versatile command-line tool available on most Unix-based systems (including Linux and macOS) and Windows. It's useful for making quick requests.

• HTTP Libraries: Most programming languages offer libraries to make HTTP requests. Examples include requests in Python, HttpClient in .NET, and axios or fetch in JavaScript.

• API Development Environments: Tools like Postman or Insomnia provide a user-friendly interface for making API requests, organizing them, and even documenting and sharing them with others.

Making an API request

To make a REST API request, follow these steps:

Here's an example using cURL to make a GET request:

curl -X GET https://api.example.com/users

And here's how you might make a POST request with cURL, including data:

curl -X POST https://api.example.com/users 
-H "Content-Type: application/json" 
-d '{"name":"John Doe","email":"john@example.com"}'

REST APIs are a powerful way to interact with web services, allowing you to leverage existing resources or create your own. By understanding the basics of REST, the HTTP methods available, choosing the right client, and knowing how to make requests, you're well on your way to integrating APIs into your projects.

Snappi conventions

While browsing through our APIs, you will encounter various notations and conventions that crucial for effective integration. Below is a detailed explanation of all the common symbols, flags and stylistic elements you may come across:

1. Field Requirements

• Required Fields:

  • Indicator: Required fields are typically marked with pink.

  • Explanation: These fields must be included in the API request for it to be successful. Omitting these fields will result in an error response.

  • Display Style: Often shown in bold text with a pink, snappi indicator next to the field name.

  • Example:

    Name

    consentId

    Type

    string(uuid)

    Description

    The unique identifier for the consent provided by the user.

2. Field Types

• Data Type Indicators:

  • String: Often represented as string or "text".

  • Integer: Denoted by integer.

  • Boolean: Shown as boolean.

  • Array/List: Represented as array[].

  • Object: Displayed as object{}.

  • Date/Time: Shown as date, datetime, or sometimes as a specific format like YYYY-MM-DD.

  • Example:

  {
   "name": "John Doe",   // string
   "age": 30,            // int
   "isActive": true,     // bool
   "tags": ["api", "doc"], // array
   "profile": {          // object
       "id": "12345",
       "role": "admin"
   },
   "created_at": "2024-08-17T00:00:00Z" // datetime
  }
  

  CopyCopied!

3. Parameter Types

• Path Parameters:
  • Indicator: Usually represented with curly braces {}.
  • Example: /users/{user_id}
  • Explanation: These are required parameters embedded within the endpoint URL, specifying the resource to be accessed.
• Query Parameters:
  • Indicator: Represented as key-value pairs after a question mark ? in the URL.
  • Example: /users?name=JohnDoe&age=30
  • Explanation: These are additional parameters that refine the response based on the query values provided.
• Header Parameters:
  • Indicator: Represented within a headers section, often shown as key-value pairs.
  • Example: "Authorization: Bearer token12345"
  • Explanation: These parameters are sent in the request header and are often used for authentication or content type specifications.
• Body Parameters:
  • Indicator: Represented as a JSON object, form data, or XML payload.
  • Example:

    {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
    

    CopyCopied!
  • Explanation: These parameters are sent in the request body, typically for POST or PUT requests.