Gitora API’s

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