View your API Definition

The organization and structure of the API definition file system facilitates better source code management and team development.
lac42
The organization and structure of the API definition file system facilitates better source code management and team development.
In this article: 
2
The Admin Repository
When API Server starts, the bootstrap process reads the file directory that is designated as the admin repository and loads the API metadata for the TeamSpaces definition, the CA Live API Creator Admin project API (Admin API) definitions that the internal system uses, and the backups definition–including resources, logic, security, filters, and Data Explorer settings–into a data model. API Server stores the data model within the in-memory Derby database. As you design your APIs, API Server creates the API metadata and writes to the admin repository.
The default repository root directory is the directory that is designated as the admin repository. The location of this directory is dependent on the Java container on which you are running 
CA Live API Creator
. For example, if you are using the self-contained, single-user version of 
CA Live API Creator
 that is based on Jetty (demonstration package) for local development, the directory location is the
%JETTY_HOME%/caliveapicreator/jetty.repository
directory.
For more information about how to set the location from you which you want
CA Live API Creator
to pull your admin repository at server startup or about setting the location to where you want
CA Live API Creator
to add the content of your admin repository at server startup, see the installation documentation for your Java container or API Server Startup Options.
Best Practices:
  • If you have installed
    CA Live API Creator
    to run on a Windows operating system, to prevent issues with long file and directory names as your API definitions expands, set the location of your admin repository under your
    c:\
    directory.
  • Use a unique admin repository directory for each Java container that you actively develop. The synchronization process in
    CA Live API Creator
    overwrites the disk with the in-memory content of the Java container.
The admin repository includes the following sub-directories for the TeamSpaces, Admin API, and backups definition:
  • teamspaces
    : The directory where API Server saves the metadata of each TeamSpace and your API definitions.
    For more information about this directory, see "The teamspaces Directory" section.
  • system
    : The directory where API Server saves the Admin API definitions.
    For more information about this directory, see "The system Directory" section.
  • backups
    : The directory where API Server creates the archives, or backups, of the changes to your API definitions.
    For more information about this directory, see "The backups Directory" section.
The following image shows an example of the admin repository for the demonstration package:
repo_root.png
Do not change the structure of the directories that API Server creates for your API in the admin repository.
You can store other files that are related to your API, such as a readMe or test data, by adding your own user directory to the admin repository. You can check out the directory of files from your source control system (SCS).
For more information about how to specify which files or directories that you want API Server to not modify or delete when you stop or restart API Server, see the "The system Directory" section.
 The synchronization process in
CA Live API Creator
 attempts to match the file system with the in-memory data model for your API metadata. Stop API Server before adding or changing the files that are in the admin repository.
For more information about how to change the content of your admin repository, see Perform Code Review Activities.
The teamspaces Directory Structure
Within admin repository, the
teamspaces
directory contains directories for each TeamSpace that you define in 
CA Live API Creator
.
The following image shows the directory structure for the
default
TeamSpace:
repo_teamspacesfolder.png
Within each TeamSpace directory, API Server creates the following files and sub-directories:
  • apis
    : This directory contains the definitions for the APIs that you created in this TeamSpace.
    For more information about
    apis
    directory structure, see the "The apis Directory Structure" section.
  • auth_providers
    : This directory contains the definitions for the custom authentication providers that this TeamSpace uses.
  • gateways
    : This directory contains the definitions for the API Gateway connections that 
    CA Live API Creator
     uses to publish APIs to API Gateway.
  • managed_servers
    : This directory contains the definition of the managed data servers that are defined under this TeamSpace.
  • teamspace_users
    : This directory contains the list of the API developers that you added to this TeamSpace as TeamSpace users.
    For more information about how to manage TeamSpace users, see Manage TeamSpace Users.
  • teamspace.json
    : This file contains the definition–the TeamSpace name and TeamSpace URL fragment–for the TeamSpace.
    For more information about how to manage TeamSpaces, see Manage TeamSpaces.
The apis Directory Structure
Within the
apis
directory, API Server creates a directory for each API. The name of each directory (the 
<apiurl>
 directory) is the unique URL fragment definition of the API.
The following image shows an example of the directory structure for the 
apis
 directory, with the 
demo
 API directory expanded:
repo_apisfolder.png
API Server creates the following files and sub-directories in the directory for each API:
  • api.json
    : This file contains the definition that 
    CA Live API Creator
    uses to recreate this API.
    Do not delete this file.
    CA Live API Creator
    requires this file.
  • apioptions.json
    : The definition containing the properties for this API.
The remaining files that API Server creates in the directory for each API have extensions that have the following extensions: .md, .json, .js, .html, or .sql. These files contain the same information that is found in API Creator. The directory and file names that API Server creates use names that correspond to objects within 
CA Live API Creator
. Your objects are organized in a .json file or are contained in directories, with the definition matching the name of the resource or entity (table or view).
For more information about the directory content, see the
readme.md
 file that is included in the directory for each API.
As you develop your API and make changes to it using API Creator, the services that are running in the background synchronize these changes to the files that are contained in the directory for each API.
Stop API server before changing the API definitions that are in the files located under the
apis
directory. When you are done changing the API definitions, load the modified API definition by restarting API server.
The security Directory
When you have specified the 
built-in authentication
 authentication provider as the authentication provider for your API, within the directory for each API, API Server creates a
security
directory for each API.
The following image shows an example of the directory structure for the 
security
 directory for the 
demo
 API:
security_directory.png
API Server creates the following sub-directories in the 
security
 directory:
  • authtokens
    : This directory contains the authentication tokens that you define in your API.
    • The demonstration package includes and uses an in-memory Derby database for your authentication tokens.
      CA Live API Creator
      dynamically creates authentication tokens in this directory when API users call the
      @authentication
      endpoint for authentication.
    • If you have created a database for your authentication tokens when you installed 
      CA Live API Creator
      ,
      CA Live API Creator
      persists the authentication tokens that it dynamically creates when API users call the
      @authentication
      endpoint in the database. For more information about this database, see Create a Database for your Authentication Tokens.
  • roles
    : This directory contains the roles for the API users.
  • users
    : This directory contains JSON files for each API user that you add in API Creator.
The system Directory
Within admin repository, the 
system
directory contains the API definitions for the Admin API that API Server uses at startup. You should not need change this content.
The following image shows the directory structure for the 
system
directory:
repo_systemfolder.png
API Server creates the following files in the 
system
 directory:
  • adminMetaCache.json
    : This file is a byte-compressed description of the in-memory Derby database. 
  • apioptions.json
    : This file lists the user settings that you can change.
  • authProviderName.json
    :
    CA Live API Creator
     bootstraps the custom authentication providers that are in the
    auth_providers
    directory using this file.
  • eula.json
    : This file is the End-User License Agreement (EULA) entry.
  • lacignore.json
    : This file lists the files and directories that you want 
    CA Live API Creator
     to not modify or delete when you stop or restart API Server.
    For more information about this file and when to add entries to it, see Configure API Directories to Source Control
  • license.json
    : This file contains a list of the API Server licenses that you have installed.
    For more information about how to import an API Server license, see Import the API Server License.
  • serverIdent.json
    : This file contains the unique identifier for this specific server instance.
CA Live API Creator
 creates the following sub-directories in the 
system
directory:
  • auth_providers
    : This directory contains a list of the authentication providers for the Admin API.
    TeamSpace
     Auth Provider
     is the default authentication provider.
  • authtokens
    : This directory contains the active authentication tokens that
    CA Live API Creator
     generates for TeamSpace users. 
    CA Live API Creator
     persists these authentication tokens for the duration of your API Server session.
  • data_sources
    : This directory contains the 
    ApiKey.json
     file, which is the definition of the data source for the authentication token database.
    For more information about this file, see Create a Database for your Authentication Tokens.
  • gateways
    : This directory contains definitions for the system TeamSpace to connect to the CA API Gateway.
    For more information about how to publish APIs to the API Gateway, see Publish an API to API Gateway.
  • libraries
    : This directory contains the JavaScript libraries that
    CA Live API Creator
     uses.
  • teamspace_users
    : This directory lists the system administrator user definitions.
The backups Directory
Within admin repository, API Server creates archives, or backups, of the changes to your API definitions in the following sub-directories in the 
backups
directory:
  • pre-image
    : Each time that you start 
    CA Live API Creator
    , API Server creates a backup of the 
    system
    and 
    teamspaces
     directories to this directory before it applies changes.
    You can view an audit trail of your changes. For more information, see View an Audit Trail of your Changes.
  • timeline
    : Each time a TeamSpace user changes your API, API Server saves a backup to this directory using the format 
    <yyyymmdd.hhmmss>
    . By default, API Server stores these backups for ten days of development activities.
    You can revert the changes to API definitions using these backups. For more information, see Revert Changes from a Backup.