This is the Gitora API documentation for version 6.1 and below. For the latest API documentation please go to this link.
Gitora Enterprise has a set of API’s that enables developers to programatically execute tasks that users can perform via the Gitora Web App such as reset, create branch, commit etc…
Below is the list of API’s with their description, input parameters and outputs.
Gitora API’s respect the authorization scheme defined in the Gitora Web App. In other words, if a user lacks the necessary privilege to perform an operation in the Gitora Web App, the corresponding API will also fail for the same user.
Introduction
After the default installation, Gitora API’s can be accesses from the URL http://[IP ADDRESS]:8080/gitora/api.
The method parameter specifies the name of the method you’d like to execute like so:
http://localhost:8080/gitora?method=login.....
Developers must log in to the API server before executing any other API call. Therefore, it makes sense to describe the login method first.
Method: login
Use to sign in to Gitora.
Parameters:
user: A valid Gitora username.
password: Password of the Gitora user.
database: The name of the database. This name is specified in the Settings->Database Connections screen in Gitora.
Output:
The login method returns a token that you need to use in every other API call.
Example: http://localhost:8080/gitora/api?method=login&user=admin&password=admin
Method: add
Add a database object to a Gitora repo.
Parameters:
name: Name of the database object
repo: Name of the repo to add the database object to.
schema: Schema of the database object to be added.
token: A valid token string received from a login API call.
type: Type of the database object to be added. Valid values are TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW
Output:
Returns null if it completes successfully. It returns an error message if the operation fails.
Example:
http://localhost:8080/gitora/api?method=add&name=EMP_PKG&repo=HR_REPO&schema=HR&token=YhfhseY45&type=PACKAGE
Method: changebranch
Changes the active branch of a Gitora repo.
Parameters:
branch: Name of the branch to switch to.
repo: Name of the repo this operation will be performed.
token: A valid token string received from a login API call.
Output:
Returns null if it completes successfully. It returns an error message if the operation fails.
Example:
http://localhost:8080/gitora/api?changebranch&branch=dev&repo=HR_REPO&token=Hhjfir7hd87
Method: checkout
Checks out the database object for a specific user.
Parameters:
object: ID of the object to check out
token: A valid token string received from a login API call.
Output:
Returns null if it completes successfully. It returns an error message if the operation fails.
Example:
http://localhost:8080/gitora/api?checkout&object=1234&token=Hdyhed7645g
Method: commit
Commits a list of objects to the specified repo.
Parameters:
message: Commit message.
ddls: A comma separated list of ID’s of DDL statements captured by Gitora.
objects=Comma separated list of object ID’s to be committed.
repo: Repo name.
token: A valid token string received from a login API call.
Output:
Returns the message received from Git.
Example:
http://localhost:8080/gitora/api?commit&message=Fixed%20the%20employee%20queries&objects=1234,4523&ddls=3642,7854&repo=HR_REPO&token=jirHJj8rfnJi
Method: createbranch
Creates a new branch in the specified repo.
Parameters:
branch: Name of the new branch.
checkout: Indicated whether the new branch should be set as the active branch. Set to true to make the new branch the active branch, to false otherwise.
commitid: Git commit ID, tag name or branch name to create the new branch from.
repo: Name of the repo to create a branch in.
token: A valid token string received from a login API call.
Output:
Returns a list of modified database objects if there are any or an error message.
Example:
http://localhost:8080/gitora/api?createbranch&checkout=true&commitid=Hdjdjhuend8874h29jdij&repo=HR_REPO&token=Kjirjdnc767yHy3
Method: createrepo
Creates a Gitora repo.
Parameters:
repo: Name of the repo to be created.
token: A valid token string received from a login API call.
Output:
Returns the message received from Git.
Example:
http://localhost:8080/gitora/api?createrepo&repo=HR_REPO&token=HJndnr8783dj
Method: deletebranch
Deletes the specified branch.
Parameters:
branch: Name of the branch to be deleted.
repo: Name of the repo the branch is in.
token: A valid token string received from a login API call.
Output:
Returns the message received from Git or an error message.
Example:
http://localhost:8080/gitora/api?deletebranch&branch=dev&repo=HR_REPO&token=Hjfurns75bdy
Method: fetchmerge
Fetches a specific commit ID from a remote repo and merges it to the specified repo’s active branch.
Parameters:
branch: The name of the remote branch to fetch from.
commitid: Git commit ID to fetch from the remote branch and merge to the active branch.
password: The password or the personal access token to connect to the remote repo. For example your GitHub personal access token. This parameter is optional. Don’t use it if the remote repo does not need a password to access.
remote: The alias specified for the remote database in the Gitora Web App.
repo: The name of the local repo.
token: A valid token string received from a login API call.
user: user name to connect to the remote repo. For example your GitHub user name. This parameter is optional. Do not use it if the remote repo does not need a user name to access.
Output:
Returns the message received from Git.
Example:
http://localhost:8080/gitora/api?fetchmerge&branch=dev&commitid=Jdudnr75hfgsj84fj&password=myPersonalAcessToken1&remote=myRemoteHRRepo&repo=HR_REPO&user=myGitHubUser&token=Hjnf74hehd
Method: fetchmergefromdb
Fetches a specific commit ID from a Gitora repo for another database and merges it to the specified repo’s active branch.
Parameters:
branch: Name of the branch to fetch from the fromrepo.
commitid= Git commit ID to fetch from the branch and merge to the active branch.
database: Name of the database the fromrepo is for.
fromrepo: Name of the repo to fetch from.
torepo: Name of the repo to merge to.
token: A valid token string received from a login API call.
Output:
Returns message received from Git.
Example:
Assume Gitora is connected to the TEST database. The example below fetches the commitid 1234 on branch master from the HR_REPO_DEV repo at the DEV database to the active branch of the HR_REPO at the TEST database.
http://localhost:8080/gitora/api?fetchmergefromdb&branch=master&commitid=1234&database=DEV&fromrepo=HR_REPO_DEV&torepo=HR_REPO&token=Hjnf74hehd
Method: getmanagedschemascript
Returns the “managed schemas script” of the specified repo.
Parameters:
repo: Name of the repo of which the developer is getting the managed schemas script.
token: A valid token string received from a login API call.
Output:
The contents of the managed schemas scrpt file, represented as the DDL_SCRIPT.sql in the Git repo.
Example:
http://localhost:8080/gitora/api?getmanagedschemasscript&repo=HR_REPO&token=Kjfur03nd8
Method: getmyobjects
Returns the list of checked out database objects by the current user.
Parameters:
repo: The repo for which the API queries the objects the user has checked out.
token: A valid token string received from a login API call.
Output:
Returns a JSON array. Each object in the array represents an database object that is checked out by the user. Each JSON object in the array has the following attributes:
id: ID of the database object in Gitora.
name: Name of the object.
schema: Schema of the object.
status: Indicates the modification state of the object. Valid values are: UNMODIFIED,MODIFIED, DELETED
type: Type of the object. (PACKAGE, PROCEDURE etc…)
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?method=getmyobjects&repo=HR_REPO&token=Jnjf744jn
Method: getrepoobjects
Returns a JSON array of database objects in the repo.
Parameters:
repo: Name of the repo to return the objects for.
token: A valid token string received from a login API call.
Output:
Returns a JSON array. Each object in the array represents a database object managed by the specified repo. Each JSON object in the array has the following attributes:
id: ID of the database object in Gitora.
name: Name of the object.
schema: Schema of the object.
status: Indicates the modification state of the object. Valid values are:
token: A valid token string received from a login API call.
type: Type of the object. (PACKAGE, PROCEDURE etc…)
UNMODIFIED,MODIFIED, DELETED
user: Name of the user who checked out the database object.
Example:
http://localhost:8080/gitora/api?method=getrepoobjects&repo=HR_REPO&token=Nkjf8nf8
Method: merge
Performs git merge.
Parameters:
commitid: Git commit ID, branch or tag name to merge to the active branch.
repo: Name of the repo to perform merge on.
token: A valid token string received from a login API call.
Output:
Returns the the text value conflict if there is a conflict after the merge or noconflict if there isn’t any.
Example:
http://localhost:8080/gitora/api?method=merge&commitid=dev&token=Hjfur84bnfr
Method: pullfromdb
Performs a Git pull from a Gitora repo for another database to the specified repo’s active branch. For example, you can pull the master branch of HR_REPO in DEV database to the master branch of HR_REPO in TEST database to move your latest code to the testing environment.
Parameters:
branch: Branch name on the fromrepo to pull.
database: Name of the database (identified in Gitora Web App under Settings->Database Connections) the from repo is for.
fromrepo: Repo to pull from.
token: A valid token string received from a login API call.
torepo: Repo to pull to.
Output:
Returns the message received from Git.
Example:
Assume thet the developer is connected to the TEST database. The example below pulls the master branch from the HR_REPO repo for DEV database to the master branch of HR_REPO repo for the TEST database.
http://localhost:8080/gitora/api?method=pullfromdb&fromrepo=HR_REPO&torepo=HR_REPO&branch=master&database=DEV&token=Hjgg6ghf
Method: push
Pushes the specified repo’s branch to a remote Git repo (which commonly resides in GitHub, GitBlit, BitBucket or a similar cloud service).
Parameters:
branch: Name of the branch to push.
password: Password or the personal access token to connect to the remote repo.
remote: The alias specified for the remote repo in the Gitora Web App under Settings–>Manage Remote Connections.
repo: Name of the repo to push.
token: A valid token string received from a login API call.
user: User name to connect to the remote repo.
Output:
Returns the message received from Git.
Example:
http://localhost:8080/gitora/api?method=push&branch=master&password=1234&remote=GitHubHRRepo&repo=HR_REPO&user=myGitHubUser1&token=Hjf85jf
Method: release
Releases the lock placed by a user on a database object. Overwrites the content of the object with the latest version available in the active branch.
Parameters:
object=ID of the database object to be released.
token: A valid token string received from a login API call.
Output:
Returns null if succeeds or an error message if it fails.
Example:
http://localhost:8080/gitora/api?method=release&object=3455&token=Hjfu57hf
Method: remove
Removes the specified database object from Gitora.
Parameters:
name: Name of the database object.
repo: Name of the repo the database object will be removed from.
schema: The schema of the object
token: A valid token string received from a login API call.
type: The type of the object. Valid values are: Valid values are TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.
Output:
Returns null if succeeds or an error message if it fails.
Example:
http://localhost:8080/gitora/api?method=remove&name=EMP_PKG&repo=HR_REPO&schema=HR&type=PACKAGE&token=Hfjuh784hnd
Method: reset
Performs the Git reset command on the active branch of the specified repo.
Parameters:
commitid: Git commit ID or tag name to reset the active branch to.
repo: Name of the repo to perform the Git reset.
token: A valid token string received from a login API call.
Output:
Returns the Git message received from Git.
Example:
http://localhost:8080/gitora/api?method=reset&commitid=375hfhd&repo=HR_REPO&token=Hjfnh894jhhnfr
Method: setmanagedschemascript
Updates the “Managed Schema Script” content and commits it.
Paramaters:
message: Commit message to be used when the new script is committed to Git.
repo: Name of the repo to set the script for.
script: The new text of the script.
token: A valid token string received from a login API call.
Output:
Returns the message received from Git.
Example:
http://localhost:8080/gitora/api?method=setmanagedschemascript&messageScript%23updated.&repo=HR_REPO&script=ALTER%23EMPLOYEES%23ADD%23COLUMN%23(MIDDLE_NAME%23VARCHAR2(200);&token=Hjhu837h
Method: switchtobranchfromdb
Fetches the branch in a repo for another database and makes it the active branch in the specified repo for the currently connected database. Used if the fetched branch is not present in the repo for the currently connected database. For example the featureA branch in HR_REPO for the DEV database may not exist in the HR_REPO for the TEST database. Using this API will bring over the featureA branch from DEV to TEST and make it the active branch.
Parameters:
branch: Name of the branch to fetch and make active.
database: The database the fromrepo is for.
fromrepo: Name of the repo to fetch the branch from.
token: A valid token string received from a login API call.
torepo: Name of the repo to fetch the branch to. It is expected that torepo does not have this branch.
Output:
Returns the message received from Git.
Example:
Assume that the featureA branch is in DEV but not in TEST database and the developer is connected to the TEST database. The example below fetches the featureA branch from the DEV database to the TEST database and makes it the active branch.
http://localhost:8080/gitora/api?method=switchtobranchfromdb&fromrepo=HR_REPO&database=DEV&torepo=HR_REPO&branch=featureA&token=Hjfi94fj4
Method: switchtoremotebranch
Fetches the branch in the remote repo and makes it the active branch in the specified repo for the currently connected database. Used if the fetched branch is not present in the repo for the currently connected database. For example the featureA branch in the remote repo GitHubHRREPOmay not exist in the HR_REPO for the TEST database. Using this API will bring over the featureA branch from remote repo to the TEST database and make it the active branch.
Parameters:
branch: Name of the branch to fetch from the remote and make active.
database: The database the fromrepo is for.
password: The password or personal access token to connect to the remote repo.
remote: Alias of the remote repo specified in the Gitora Web App under Settings–>Manage Remote Repos.
repo: Name of the repo to fetch the branch to. It is expected that torepo does not have this branch.
token: A valid token string received from a login API call.
user: User name to connect to the remote repo.
Output:
Returns the message received from Git.
Example:
Assume that the featureA branch is in remote GitHubHRRepo but not in local HR_REPO for the TEST database and the developer is connected to the TEST database. The example below fetches the featureA branch from the GitHubHRRepoto the TEST database and makes it the active branch.
http://localhost:8080/gitora/api?method=switchtoremotebranch&remote=GitHubHRRepo&torepo=HR_REPO&branch=featureA&user=myGitHubUser&password=1234&token=Hjfi94fj4