View your API Definition

The organization and structure of the API definition file system facilitates better source code management and team development.
lac53
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 Layer7 Live API Creator 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 depends on the Java container on which you are running 
Layer7 Live API Creator
. For example, if you are using the self-contained, single-user version of 
Layer7 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 
Layer7 Live API Creator
 to pull your admin repository at API Server startup or about how to set the location to where you want 
Layer7 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 
    Layer7 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 for each Java container on which you actively develop. The synchronization process in 
    Layer7 Live API Creator
     overwrites the disk with the in-memory content of the Java container.
The admin repository includes the TeamSpaces, Admin API, and backups definition in the following sub-directories:
  • 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 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 
Layer7 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
Within admin repository, the 
teamspaces
 directory contains directories for each TeamSpace that you define in 
Layer7 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 
    Layer7 API Gateway
     connections that 
    Layer7 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
Layer7 Live API Creator
 includes your API metadata, including your resource and function definitions, in the directory for your API within the 
apis
 directory. 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 
    Layer7 Live API Creator
     uses to recreate this API.
    Layer7 Live API Creator
     requires this file. Do not delete it.
  • 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 
Layer7 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 from the admin repository into API Server 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. 
      Layer7 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 
      Layer7 Live API Creator
      Layer7 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. The following image shows the directory structure for the 
system
 directory:
system_adminrepository.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
    Layer7 Live API Creator
     bootstraps the custom authentication providers that are in the 
    auth_providers
     directory using this file.
  • eula.json
    : This file is the entry for the End-User License Agreement (EULA).
  • lacignore.json
    : This file lists the files and directories that you want 
    Layer7 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.
  • telemetry.json
    : This file contains the configuration that 
    Layer7 Live API Creator
     uses to send usage data.
    For more information about how to configure this file for your API deployment to other environments, see Activate and Configure to Send Usage Data.
Layer7 Live API Creator
 creates the following sub-directories in the 
system
 directory:
  • auth_providers
    : This directory contains the authentication providers for the Admin API. The 
    TeamSpace
     
    Auth Provider
     authentication provider is the default authentication provider.
    For more information about authentication provider for the Admin API, see Change the Authentication Provider for the Admin API.
  • authtokens
    : This directory contains the active authentication tokens that 
    Layer7 Live API Creator
     generates for TeamSpace users.
    For more information about authentication tokens, see Manage API Users.
  • data_source_providers
    : This directory contains the data source providers that 
    Layer7 Live API Creator
     includes and other data source providers that you define to be made available for your APIs.
    For more information about how to define your own data source providers, see Manage Data Source Providers.
  • 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 API Gateway.
    For more information about how to publish APIs to API Gateway, see Publish an API to API Gateway.
  • libraries
    : This directory contains the JavaScript libraries that 
    Layer7 Live API Creator
     uses.
  • listener_providers
    : This directory contains the listener provider definitions that 
    Layer7 Live API Creator
     includes.
     
    Layer7 Live API Creator
     includes a set of default listener providers. Do not change or delete them. Restarting API Server resets and reloads them.
    For more information about listener providers, see Manage Listener Providers.
  • teamspace_users
    : This directory contains the system administrator (
    sa
    ) 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 
    Layer7 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.