Appendix

Appendix

API Core Concepts

In the following table, you will find basic API-related vocabulary descriptions:

API Vocabulary	Description
Resources	Paths on a server where the API stores and provides data. For example: /users, /users/{id}, and /{id}/products. Think of them as unique URLs for specific pieces of information.
Method	The action you want to perform on a resource, defined by an HTTP verb. The most common ones are: GET - To read a resource. POST - To create a new resource. PUT - To completely replace or update a resource. DELETE - To remove a resource. PATCH - To partially update a resource.
Request	A structured message sent by a client (System A) to a server (System B) . This message includes the desired Method, the Resource path, and sometimes data. An example is: HTTP GET http://www.appdomain.com/users.
Response	The structured answer a server (System B) sends back to a client (System A) after receiving a Request. It includes an HTTP Status Code, an optional message, and the requested data. The most common data formats are JSON and XML.
Status Codes and Messages	HTTP protocol numeric codes and messages that tell you the result of a Request whether a request was successful, failed, or needs more information. The codes are grouped into five categories: 1xx (Informational), 2xx (Success), 3xx (Redirection), 4xx (Client Errors), and 5xx (Server Errors).
Authentication	The process of verifying a user’s or client’s identity. It’s like showing your ID to prove you are who you say you are before you can access an API.
Authorization	The process of checking if an authenticated user or client has permission to access a specific resource or perform a certain action.
Data Structure or Schema	The blueprint or rules for organizing the data that is exchanged between the client and the server. It defines what fields are required, their data types, and how the information should be organized. The most popular formats for this are JSON and XML.

Visual API Workflow (Epic Alternative Diagram)

Python API Code Example

In the following Python code example, you will find a simple API code with explanatory comments:

from flask import Flask, request, jsonify

# This line creates our web application. Think of it like opening our pet store's front door
# ready to receive visitors (requests).
app = Flask(__name__)

# --- Our Pet Store's "Database" (just a simple list for this example) ---
# This is where we keep track of our pets. Each pet has an ID, a name, a species, and a status.
# In a real store, this would be a proper database.
pets = [
    {"id": "p1", "name": "Buddy", "species": "dog", "status": "available"},
    {"id": "p2", "name": "Whiskers", "species": "cat", "status": "available"},
    {"id": "p3", "name": "Goldie", "species": "fish", "status": "adopted"},
]

# --- API Endpoint: Get All Pets or a Specific Pet ---
# This is like asking "What pets do you have?" or "Tell me about pet p1?"
# The address for this is typically '/pets' or '/pets/<pet_id>'
@app.route('/pets', methods=['GET'])
def get_pets():
    # If someone asks for all pets (e.g., visiting '/pets'), we give them the full list.
    return jsonify(pets)

@app.route('/pets/<string:pet_id>', methods=['GET'])
def get_pet(pet_id):
    # This loop goes through our pet list to find the one with the matching ID.
    for pet in pets:
        if pet['id'] == pet_id:
            # If we find the pet, we show its details.
            return jsonify(pet)
    
    # --- Error Handling Example 1: Pet Not Found ---
    # If we look through all our pets and can't find the one requested,
    # we send back a "404 Not Found" message. This tells the requester
    # that the pet ID they provided doesn't exist in our store.
    return jsonify({"error": "Pet not found"}), 404

# --- API Endpoint: Update an Existing Pet ---
# This is like telling the store, "I want to change something about pet p1."
# The address is '/pets/<pet_id>' and we use the 'PUT' method.
@app.route('/pets/<string:pet_id>', methods=['PUT'])
def update_pet(pet_id):
    # We expect the person sending the request to also send us the new details
    # for the pet in a structured format (JSON).
    data = request.get_json()
    
    # --- Error Handling Example 2: Missing Data ---
    # We check if they actually sent us any new information. If 'data' is empty,
    # it means they didn't provide any updates, so we send a "400 Bad Request" error.
    if not data:
        return jsonify({"error": "No data provided for update"}), 400

    # Find the pet in our list that matches the ID.
    for pet in pets:
        if pet['id'] == pet_id:
            # Once found, we update its information with the new data received.
            # For example, if 'name' was in the data, we update the pet's name.
            pet.update(data)
            # Then we send back the updated pet's details as confirmation.
            return jsonify(pet)
            
    # If we can't find the pet to update, it's another "404 Not Found" error.
    return jsonify({"error": "Pet not found"}), 404

# --- How to Run Our Pet Store API ---
# This part makes our pet store "open for business" on your computer.
# When you run this Python file, it starts a small web server.
# You can then access it through your web browser or other tools.
if __name__ == '__main__':
    app.run(debug=True) # 'debug=True' is helpful for development, shows more info if something goes wrong.

API Design Approaches

In the following table, you'll find an informative description of the different API design approaches:

API Coding Approach	Description	Pros	Cons
Code-First	You start by writing your API's implementation code, then use tools or annotations within your code to generate the API specification (like OpenAPI/Swagger) automatically. The code is the source of truth.	- Faster development: Jump straight into coding with auto-generated documentation. - Always synchronized: Documentation updates automatically with code changes.	- Design can be an afterthought: May lead to less consistent or well-thought-out API designs. - Tool dependency: Relies heavily on code generation tools, which might have limitations.
API Design-First	You begin by designing and defining your API using an API specification language (like OpenAPI/Swagger, RAML, API Blueprint) before writing any code. Tools then generate boilerplate code or documentation from this specification.	- Improved API quality: Forces thoughtful design from the start. - Early feedback: Stakeholders can review the API design before development begins. - Parallel development: Frontend and backend teams can work concurrently using the spec.	- Slower initial setup: Requires an extra design step before coding begins. - Syncing challenges: If code deviates from the spec, manual updates are needed.
Hybrid Approach	Combines elements of both Code-First and Design-First. You might start with a high-level design document or a rough spec, then implement the core API with Code-First tools, and finally refine the specification and code iteratively.	- Balances speed and quality: Get started quickly but still benefit from design principles. - Flexibility: Can adapt to project needs and team strengths.	- Complexity: Can be harder to manage the workflow and keep everything synchronized. - Requires discipline: Needs a clear process to ensure design and code remain aligned.

OpenAPI and Arazzo Specifications

In the following table you'll find a description of the OpenAPI and Arazzo specifications and the best use cases for them:

API Specification	Description	Best Use Cases
OpenAPI Specification (OAS)	A widely adopted, language-agnostic standard for describing RESTful APIs. It focuses on defining the API's surface: endpoints, operations, parameters, responses, and security schemes. It's essentially the blueprint for what an API does.	- Defining API Contracts: Creating a clear, machine-readable definition of a REST API. - Automated Tooling: Generating documentation (Swagger UI), client SDKs, server stubs, and testing tools. - Design-First Development: Collaborating on API design before coding begins. - API Discovery & Consumption: Helping developers understand and integrate with APIs quickly.
Arazzo Specification	A new specification focused on describing API-level callbacks, webhooks, and asynchronous API interactions. Unlike OpenAPI, which defines the initial request-response contract, Arazzo describes the events and messages that an API might send or receive asynchronously after an initial request, often involving a client-provided callback URL. It provides a formal way to define "reverse calls" or event-driven patterns in APIs.	- Defining Webhooks: Clearly specifying how an API will notify a client of events. - Asynchronous API Workflows: Documenting long-running processes where the API calls back to the client upon completion or status change. - Event-Driven Architectures: Formalizing the structure of events and callback messages. - Microservices Communication: Detailing asynchronous inter-service communication patterns where one service triggers actions in another via callbacks. - Enhancing OpenAPI: Arazzo is designed to complement OpenAPI, describing the asynchronous behavior of an API that OpenAPI defines the synchronous interface for.

OpenAPI Specification Example

The following piece of an incomplete OpenAPI specification file shows some of those objects:

openapi: 3.0.4
info:
externalDocs:
servers:
tags:
  /pet:
    put:
      tags:
      summary: Update an existing pet.
      description: Update an existing pet by Id.
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
paths:
components:

Complete openAPI specification

Check a complete example of an openAPI specification to have a wider view of its content.