.. _mds-api:

Confluent Metadata API Reference
================================

The Confluent Metadata API has many endpoints, conceptually grouped as follows:

**Authentication**
   
Authenticates users against LDAP and returns user bearer tokens that can be used 
with the other MDS endpoints and components in |cp| (when configured to do so).

**Authorization**
   
Authorizes users to perform specific actions. Clients are not expected to use 
these endpoints, which are used by |cp| components (such as Connect and KSQL) to 
authorize user actions.

**Role Based Access Control**

* Role binding CRUD
* Role binding summaries (used by Confluent CLI)
* High-level role binding management and rollups (used by |c3|)

**Centralized ACL Control**

* With :ref:`authorization-acl-with-mds` |cp| provides the option to store ACLs 
  in |ak| instead of |zk|
* ACL CRUD for legacy |ak|-managed and centralized MDS-based ACLs

Access Restrictions
-------------------

Some endpoints can be called by any authenticated user, while others can
only be called by "admins". Additionally, many of the endpoints in the
API involve two users: the user who is calling the endpoint (the
"calling" principal) and the user that the API call is about (the
"target" principal).

Example: User "alice", who has the UserAdmin role, and is identified by
her basic auth credentials or a bearer token, calls the CRUD endpoint to
modify role bindings about user "bob".

To document what access restrictions each endpoint has, use the
following legend, which lists access in order from least restrictive to
most restrictive:

LDAP
   Any authenticated LDAP user
   
Admins+User
   Admins or users requesting information about themselves
   
Admins+ResourceOwners
   Admins or users with ResourceOwner role
   
Admins+AclUsers
   Admins or the user having the required ACL permissions

Admins
   Admins only, which can be UserAdmin, SystemAdmin, broker super.user, or 
   SecurityAdmin as "Read"

Overview of Responses
---------------------

**Valid Responses**

-  200: Successful call with a return body.
-  204: Successful call with no return body.

**Errors**

-  400: Invalid request. JSON parsing error, or otherwise incorrect request.
-  401: Not Authenticated. You need to pass valid basic auth credentials or a 
   user bearer token.
-  403: Not Authorized. Valid request, but you aren't authorized to perform the 
   requested action.
-  404: Invalid URL. If you get this error from the authenticate endpoint, it 
   means bearer token authentication needs to be enabled in the configuration 
   (``confluent.metadata.server.authentication.method=BEARER``)

-  405: Method Not Allowed. Using the wrong HTTP method on a valid endpoint 
   (for example, GET instead of POST).
-  415: Invalid Content Type. Usually, not sending "application/json" as request 
   body header.
-  500: Server Error.

Special Resource Types
----------------------

Cluster and KsqlCluster are special ResourceTypes because they grant
resource-scoped roles like ResourceOwner and DeveloperManage limited
access to cluster-level operations (for example, Describe Configs on
|ak| clusters). These special resource types only accept LITERAL
patterns with the values ``kafka-cluster`` and ``ksql-cluster``,
respectively.

Exploring the API
-----------------

The Metadata Service ships with an OpenAPI spec which can be explored and interacted with using an
embedded Swagger UI.

To enable the embedded Swagger UI, add the following to the broker's config when also configuring
the Metadata Service.
``confluent.metadata.server.openapi.enable=true``

This will make the Swagger UI available on the broker as ``http://<host>:<port>/security/openapi/swagger-ui/index.html``.

.. warning::  The Swagger UI and the Open API spec file are provided for development and test purposes only:

  - **Do not enable in production environments.**
  - **The Swagger UI works only with HTTP.**

Private RBAC UI Endpoints
---------------------------

These endpoints were developed specifically to power the |c3| UI. As such, they 
only focus on those use cases and have only been tested in the context of |c3|. These
endpoints have not been tested, nor has their usability been evaluated
with respect to manual API calls.    

API Endpoints
-------------

.. openapi:: ../../.hidden/metadata-service/rbac-api-server/src/main/resources/WEB-INF/openapi/mds-spec-1_0.yaml	
    :group:	
    :examples: