This is the Gitora API documentation for version 6.2 and above. For the API documentation of the older versions 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.....
Output of API Calls
Each API call returns a JSON Object. This object has the following three properties:
message: The message returned from the API, if any.
result: returns the word success if the API was executed successfully or the word error if there was an error during the execution.
If the result property returns the value error then the message property contains the error message.
token: Returns the token value to be used to call other API’s. This property is only populated after a successful call to the login API.
Developers must receive a token from the login API before executing any other API call. Therefore, it makes sense to describe the login method first.
Method: authenticate
Use to sign in to Gitora. It returns a token that you can use to execute other API’s.
Parameters:
user: A valid Gitora username.
password: Password of the Gitora user.
database: The name of the database to log in to. This name is specified in the Settings->Database Connections screen in Gitora.
Example: http://localhost:8080/gitora/api?method=authenticate&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
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.
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:
schema: Schema of the object to check out.
type: Type of the object to check out: Valid values are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.
name: Name of the object to check out.
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?checkout&object=1234&token=Hdyhed7645g
Method: reset
Performs the Git reset command on the active branch of the specified repo.
Parameters:
repo: Name of the repo to perform the Git reset.
commitid: Git commit ID or tag name to reset the active branch to.
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: commit
Commits a list of objects to the specified repo.
Parameters:
message: Commit message.
ddls: A JSON array of DDL statement ID’s captured by Gitora.
objects= A JSON array of database objects. Example: [{“schema”:”DEV”, “type”:”PACKAGE”, “name”:”HR_PKG”},{“schema”:”DEV”, “type”:”PROCEDURE”, “name”:”HIRE_EMP”}] . Valid values for type are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.
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= [{"schema":"DEV", "type":"PACKAGE", "name":"HR_PKG"},{"schema":"DEV", "type":"PROCEDURE", "name":"HIRE_EMP"}] &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: Indicates whether the new branch should be set as the active branch. Set to true to make the new branch the active branch, to false if you’d like the keep the current active branch.
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.
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.
type: Type of the repo to be created. Valid values: msr (Multi Schema Repo), ssr (Single Schema Repo)
schema: This parameter is only valid for single schema repos. It indicated which schema the repo is for.
track: Indicates whether this repo should track hard object changes in this repo. Valid values are: Y (for the schema to track the hard object changes), N (for the schema not to track hard object changes.)
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?createrepo&repo=HR_REPO&type=msr&token=HJndnr8783dj
http://localhost:8080/gitora/api?createrepo&repo=HR_REPO2&type=ssr&schema=HR&track=Y&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.
Example:
http://localhost:8080/gitora/api?deletebranch&branch=dev&repo=HR_REPO&token=Hjfurns75bdy
Method: fetchfromdb
Fetches a branch from a Gitora repo to another.
Parameters:
fromdatabase: The name of the database to fetch from. (Name of the database connection in Gitora.)
fromrepo: The name of the repo to fetch from.
frombranch: The name of the branch to fetch.
torepo: The name of the repo to fetch to. (The destination repo.)
tobranch: The name of the branch in the destination repo.
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?fetchfromdb&frombranch=feature_1&fromrepo=HR_REPO&fromdatabase=DEV&torepo=HR_REPO&tobranch=feature_1&&token=Hjnf74hehd
Method: fetchfromremote
Fetches a branch from a remote repo to a Gitora repo.
Parameters:
torepo: The name of the Gitora repo. to fetch to.
tobranch: The name of the branch to fetch to.
remote: The alias specified for the remote database in Gitora.
remotebranch: The name of the remote branch to fetch from.
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.
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.
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?fetchfromremote&torepo=HR_REPO&tobranch=feature_1 &remotebranch=feature_1&password=myPersonalAcessToken1&remote=myRemoteHRRepo&user=myGitHubUser&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.
Example:
http://localhost:8080/gitora/api?getmanagedschemascript&repo=HR_REPO&token=Kjfur03nd8
Method: getmyobjects
Returns the list of checked out database objects by the signed in 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 a 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.
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.
token: A valid token string received from a login API call.
type: Type of the object. (PACKAGE, PROCEDURE etc…)
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.
Example:
http://localhost:8080/gitora/api?method=merge&repo=HR_REPO&commitid=Uhee8jGdy&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:
fromdatabase: Name of the database the pull from. (Name of the database connection in Gitora.)
fromrepo: Repo to pull from.
frombranch: Branch name to pull.
torepo: Repo to pull to.
token: A valid token string received from a login API call.
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&fromdatabase=DEV&fromrepo=HR_REPO&frombranch=master&torepo=HR_REPO&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: 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.
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: 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=JSON Object specifying the database object to be released. Example: {“schema”:”HR”, “type”:”PACKAGE”, “name”:”HR_PKG”}. Valid values for type are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?method=release&object= {"schema":"HR", "type":"PACKAGE", "name":"HR_PKG"} &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
type: The type of the object. Valid values for type are: TABLE, PACKAGE, VIEW, PROCEDURE, FUNCTION, TRIGGER, SYNONYM, TYPE, SEQUENCE, MATERIALIZED_VIEW.
token: A valid token string received from a login API call.
Example:
http://localhost:8080/gitora/api?method=remove&name=EMP_PKG&repo=HR_REPO&schema=HR&type=PACKAGE&token=Hfjuh784hnd