Getting Started

EnterMediaDB provides APIs for managing your media assets, including uploading files, searching assets, and uploading metadata.

There are two ways to interact with the API, depending on your goal.

1. Choose How You Want to Use the API

Before making any requests, choose one of the following options:

Option 1: JSON REST API (Recommended for Development)

The JSON REST API is the primary method for interacting with EnterMediaDB. Use this option for all production and development work.

Use the REST API if you want to:

  • Build an application or integration
  • Automate workflows
  • Write scripts (Python, JavaScript, etc.)
  • Connect EnterMediaDB to another system

How it works:

  • Send HTTP requests (GET, POST, PUT, DELETE)
  • Include JSON data in the request (when required)
  • Receive JSON responses

Example use cases:

  • Automatically uploading files
  • Syncing data between systems
  • Building a custom dashboard

Option 2: EnterMediaDB API UI

The EnterMediaDB API UI is a built-in interface for testing and exploring API endpoints. Use this option for testing, learning, and debugging.

Use the API UI if you want to:

  • Test API requests without writing code
  • Explore available endpoints
  • Debug or troubleshoot requests
  • Learn how the API works

How it works:

  • Open the EnterMediaDB interface
  • Select an API module (e.g., Upload File)
  • Choose a request method (GET, POST, etc.)
  • Enter your JSON request
  • Run the request and view the response

2. Recommended Workflow for New Users

If you are new to the API, follow these steps:

  1. Start with the EnterMediaDB API UI to explore endpoints and understand how requests work
  2. Test different inputs and review the responses
  3. Move to the JSON REST API to implement your solution in code

3. Authentication (Required)

Before using either the JSON REST API or the EnterMediaDB API UI, you must:

  • Log in to EnterMediaDB
  • Ensure your user has API permissions
  • Obtain your session cookie (entermedia.key)
Step 1: Log in to EnterMediaDB

  1. Open the main site in your browser

    Example:
    https://emedialibrary.org

  2. Log in using your username and password
Step 2: Open the EnterMediaDB API Interface

  1. In your browser URL, add /mediadb after your domain

    Example:
    https://entermediadb.org/mediadb

  2. Press Enter

This will open the MediaDB API interface, where you can:

  • Test API requests (API Tool)
  • Access API-related settings
Step 3: Enable API Permissions

Your user account must have permission to use the API.

To enable permissions:

  1. Open your library site

    Example:
    https://emedialibrary.org/find/

  2. Go to Settings → Site Permissions

  3. In Choose Role, select Users

  4. Scroll to Programming API
  5. Enable required permissions:
    • Select all for full access
    • Or choose specific permissions (e.g., read-only)

Important Notes:

  • If you don’t see the Programming API section:
    • You may not have sufficient permissions
    • Contact your administrator
Step 4: Initialize the API Session

Before making regular API requests, you must initialize your API session.

How it works:

  • You make your first API request
  • EnterMediaDB generates and returns an entermedia.key cookie
  • The client stores this cookie
  • The cookie is reused for future requests

Important Notes:

  • The cookie does not expire easily
  • It allows automatic login for future requests
  • No need to log in again if the cookie is preserved

4. Calling the API

After initializing the session, include the entermedia.key cookie in all API requests.

Example: Test API Call (Hello World)
curl -H "Content-Type: application/json" \
  -X POST \
  http://em9dev.entermediadb.org/assets/mediadb/services/test/helloworld \
  -b "entermedia.key=YOUR_SESSION_KEY"
 

Notes:

  • Replace YOUR_SESSION_KEY with your actual key

  • If using HTTPS, include -L to follow redirects:

    curl -L ...

API Tool (UI)

  • No manual cookie handling required
  • The browser automatically manages the session

5. Module API (Overview)

EnterMediaDB automatically generates API endpoints for each module.

Key points:

  • Each module includes standard CRUD operations:
    • Create
    • Read
    • Update
    • Delete
  • New modules automatically expose API endpoints

Reloading Modules

If expected endpoints are missing:

  1. Open the MediaDB API UI
  2. Click Load Modules (top-left corner)

Note: Typically required only after upgrading EnterMediaDB

1.6 Creating a Custom API (Advanced)

Advanced users can create custom API endpoints.

High-Level Steps

  1. Create a configuration file:

    /mediadb/services/mystuff/hello.xconf
  2. Define your API path and action in the configuration

  3. Copy the plugin configuration:

    /WEB-INF/base/mediadb/src/plugin.xml  
→ /WEB-INF/base/mystuffapp/src/plugin.xml
  4. Restart the Tomcat server
    • Required because objects are cached
  5. Register your API in the database using:
    • docsection table
    • endpoint table

Notes:

  • Requires developer experience with EnterMediaDB
  • Intended for advanced use cases only
[API, diy, Example, JSON]