The DBB server provides REST services to create, read, update, and delete objects from the DBB database. The services accept and return objects in XML or JSON format.
A Collection represents an SCM branch or stream. The dependency data related APIs will require a unique collection name.
id: A unique ID assigned by the system to identify individual Collection objects.
name: Unique name for a Collection.
logicalFile: See Logical File Service NOTE: JSON format will use the field name "logicalFiles".
owner: The owner of this object. The default value is the creator of the object.
team: The team with access authority to the object. The default value is null.
permission: The type of authority that an owner, team, or individual has to the object. The permission is represented by a three-digit octal number. See Permission Details for more information.
A POST can be used to create a Collection. Use the Content-Type header to indicate the format of the request body. Logical file metadata is optional and may be added in a separate POST request.
Example request URL: https://localhost:9443/dbb/rest/collection
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the item created.
Example response URL: https://localhost:9443/dbb/rest/collection/1351
| Content-type | Example of request body |
|---|---|
| application/json | { |
| application/xml | <collection> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A POST can be used to create a Collection from another Collection. A request body is not expected and will be ignored if provided. The new collection becomes a copy of the source collection with a new name.
Example request
URL: https://localhost:9443/dbb/rest/collection/{new_name}?source={id_or_name}
Where:
new_name:
becomes the name of the new collection. The new name must be unique.
id_or_name: is the id or unique name of the existing collection that is being copied.
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the item created.
Example response URL: https://localhost:9443/dbb/rest/collection/1351
A POST or PUT can be used to add logical file metadata to an existing Collection. Use the Content-Type header to indicate the format of the request body. Logical file metadata will be merged with the existing logical file metadata that is already part
of the collection. Use the Logical File DELETE API to remove a logical file from a collection.
Example request URL: https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile
Where:
id:
is the unique id number assigned when the collection is created.
name: is the unique name supplied during collection creation.
A successful POST will return a 200 response code.
| Content-type | Example of request body |
|---|---|
| application/json | [{ |
| application/xml | <logicalFiles> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A GET request without a collection id or name as part of the URL is used to read the contents of all collection objects. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Optionally, you may
add minimal to the URL to eliminate logical file metadata from the response. Minimal is recommended for large collections or large number of collections to limit the amount of data returned.
Example request URL: https://localhost:9443/dbb/rest/collection or https://localhost:9443/dbb/rest/collection/minimal
A successful GET will return a 200 response code.
| Accept | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <collections> |
| text/plain | Not Supported |
A GET request with an ID or name as part of the URL is used to read the contents of an individual collection object. The request Accept header will determine the format (XML or JSON) of the output in the response body. The URL returned from the POST
is used to perform the GET. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET. Optionally, you may add minimal to the URL to eliminate logical file metadata from the
response. Minimal is recommended for large collections to limit the amount of data returned.
Example request URL: https://localhost:9443/dbb/rest/collection/468 or https://localhost:9443/dbb/rest/collection/Collection1/minimal
id: is the unique id number assigned
when the collection is created.
name: is the unique name supplied during collection creation.
A successful GET will return a 200 response code.
| Accept | Example of Response Body |
|---|---|
| application/json | { |
| application/xml | <collection id="468"> |
| text/plain | Not Supported |
A GET request with an ID or Collection name and followed by logicalFile as part of the URL is used to read the logical file metadata of an individual collection object. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Additionally, one or more query parameters may be used to further limit the content that is returned.
lname: returns logical file metadata where lname equals the supplied value.
file:
returns logical file metadata where file equals the supplied value.
language: returns logical file metadata where language equals the supplied value.
cics: limits
result to logical files whose source contains EXEC CICS statements (cics, cics=y, cics=yes, cics=true equate to true. All other values equate to false.)
sql: limits result to logical files whose source contains
EXEC SQL statements (sql, sql=y, sql=yes, sql=true equate to true. All other values equate to false.)
dli: limits result to logical files whose source contains DLI statements (dli, dli=y, dli=yes, dli=true
equate to true. All other values equate to false.)
Example request URL:
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile
id:
is the unique id number assigned when the collection is created.
name: is the unique name supplied during collection creation.
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?lname=EPSMLIST&file=MortgageApplication/cobol/epsmlist.cbl&language=COB
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics
returns all logicalFiles that contain EXEC CICS commands
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics=true
returns
all logicalFiles that contain EXEC CICS commands
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics=false
returns
all logicalFiles that do not contain EXEC CICS commands
A successful GET will return a 200 response code.
| Accept | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <logicalFiles> |
| text/plain | Not Supported |
A DELETE request is used to delete a collection object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL returned from the POST is used to perform
the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/collection/{id_or_name}
id:
is the unique id number assigned when the collection is created.
name: is the unique name supplied during collection creation.
A successful DELETE will return a 200 response code.
A DELETE request with an ID or Collection name and followed by logicalFile as part of the URL is used to delete the logical file(s) of an individual collection object.
Additionally, one or more query parameters may be used to further limit the scope of the delete.
lname: deletes logical file metadata where lname equals the supplied value.
file:
deletes logical file metadata where file equals the supplied value.
language: deletes logical file metadata where language equals the supplied value.
cics: deletes
logical file metadata where the source contains EXEC CICS statements (cics, cics=y, cics=yes, cics=true equate to true. All other values equate to false.)
sql: deletes logical file metadata where the source
contains EXEC SQL statements (sql, sql=y, sql=yes, sql=true equate to true. All other values equate to false.)
dli: deletes logical file metadata where the source contains DLI statements (dli, dli=y, dli=yes,
dli=true equate to true. All other values equate to false.)
Example request URL:
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile
id:
is the unique id number assigned when the collection is created.
name: is the unique name supplied during collection creation.
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?lname=EPSMLIST&file=MortgageApplication/cobol/epsmlist.cbl&language=COB
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics
deletes all logicalFiles in collection that contain EXEC CICS commands
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics=true
deletes
all logicalFiles in collection that contain EXEC CICS commands
https://localhost:9443/dbb/rest/collection/{id_or_name}/logicalFile?cics=false
deletes
all logicalFiles in collection that do not contain EXEC CICS commands
A successful DELETE will return a 200 response code.
A PUT is used to update a Collection. Note that only the name, owner, team, and permission can be updated. If other fields are included in the XML or JSON body, they will be ignored. Updating logical files and logical dependencies must be done via the appropriate update services.
Example request URL: https://localhost:9443/dbb/rest/collection/{id}
Where:
id: is the unique id number assigned when the collection is created.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| application/json | { |
| application/xml | <collection> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
The logical file is the metadata representation of a file in the source code management system.
id: A unique ID assigned by the system to identify individual build request objects.
lname: Logical name of the file represented by this metadata.
file: Relative path and file name associated
with this file.
language: Optional field used to denote the programming language for the file.
cics: Source contains EXEC CICS statements. The default value is false.
sql: Source contains
EXEC SQL statements. The default value is false.
dli: Source contains DLI statements. The default value is false.
logicalDependency: See Logical Dependency. NOTE: JSON format will use the field name logicalDependencies.
A POST or PUT adds new logicalFile(s) to the collection. A logicalFile that already exists for this collection with same dependencies are not modified. An existing logicalFile with different dependencies are unlinked from the collection and a new logicalFile
is created. This is equivalent to using the Collection POST or PUT (Add logical files) Service. Use the Logical File DELETE API to remove a logical file from a collection.
Example
request URL: https://localhost:9443/dbb/rest/logicalFile?collection={id_or_name}
collection: A required
query parameter specifying the id or name of an existing collection
A successful POST will return a 200 response code.
| Content-type | Example of request body |
|---|---|
| application/json | [ { |
| application/xml | <logicalFiles> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A GET request without a logical file id as part of the URL is used to read the contents of all logical file objects. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Additionally, one or more query parameters may be used to further limit the content that is returned.
lname: limits result to logical files where lname parameter equals logical file name field.
file:
limits result logical files where file parameter equals the logical file file field.
language: limits result to logical files where language parameter equals the logical file language field.
cics:
limits result to logical files whose source contains EXEC CICS statements (cics, cics=y, cics=yes, cics=true equate to true. All other values equate to false.)
sql: limits result to logical files whose source
contains EXEC SQL statements (sql, sql=y, sql=yes, sql=true equate to true. All other values equate to false.)
dli: limits result to logical files whose source contains DLI statements (dli, dli=y, dli=yes,
dli=true equate to true. All other values equate to false.)
collection: limit search to logical files in a collection
ld.lname: limits results to logical files
with a logical dependency where ld.lname equals the logical dependency logical name.
ld.library: limits results to logical files with a logical dependency where ld.library equals the logical dependency library.
ld.category:
limits results to logical files with a logical dependency where ld.category equals the logical dependency category.
Example request URL:
https://localhost:9443/dbb/rest/logicalFile
returns all logicalFiles
https://localhost:9443/dbb/rest/logicalFile?lname=EPSMLIST
returns all logicalFiles with an lname of EPSMLIST
https://localhost:9443/dbb/rest/logicalFile?lname=EPSMLIST&collection=MortgageApp
returns
all logicalFiles with an lname of EPSMLIST and is part of the MortgageApp collection
https://localhost:9443/dbb/rest/logicalFile?ld.lname=EPSMORTF&ld.library=SYSLIB&ld.category=COPY&collection=MortgageApp
returns
all logicalFiles in collection MortgageApp that have a dependency on copybook EPSMORTF in library SYSLIB.
https://localhost:9443/dbb/rest/logicalFile?cics
returns
all logicalFiles whose source contains EXEC CICS statements.
https://localhost:9443/dbb/rest/logicalFile?cics=false
returns
all logicalFiles whose source does not contain EXEC CICS statements.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <logicalFiles> |
| text/plain | Not Supported |
A GET request with an ID as part of the URL is used to read the contents of an individual logical file object. The request Accept header will determine the format (XML or JSON) of the output in the response body. The number on the URL corresponds with
the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/logicalFile/30
A successful GET will return a 200 response code.
| Accept Heaader | Example of Response Body |
|---|---|
| application/json | { |
| application/xml | <logicalFile id="30"> |
| text/plain | Not Supported |
A GET request with an ID as part of the URL and followed by LogicalDependency is used to read the list of logical dependencies of an individual logical file object. The request Accept header will determine the format (XML or JSON) of the output in the
response body.
Example request URL: https://localhost:9443/dbb/rest/logicalFile/{id}/logicalDependency
Optional query parameters may also be used to limit the amount of data that is returned
ld.lname: limits results to logical files with a logical dependency where ld.lname equals the logical dependency logical
name.
ld.library: limits results to logical files with a logical dependency where ld.library equals the logical dependency library.
ld.category: limits results
to logical files with a logical dependency where ld.category equals the logical dependency category.
A successful GET will return a 200 response code.
| Accept header | Example of Response Body |
|---|---|
| application/json | [ |
| application/xml | <logicalDependencies> |
| text/plain | Not Supported |
A DELETE request is used to delete a logical file from a collection. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary.
Example request URL:
https://localhost:9443/dbb/rest/logicalFile/{id}?collection={id_or_name}
Deletes
a specific logical file from a collection.
https://localhost:9443/dbb/rest/logicalFile?collection={id_or_name}&lname=<lname>&file=<file>&language=<language>
Delete
logical file(s) meeting query criteria from a collection:
Where:
id: (required for this form of URL)id number assigned to a specific logical file object
Required query parameters:
collection: (required)remove the logical file from a collection identified by the collection id number or collection name.
Optional Query parameters:
lname: logical name of the logical file to be removed from a collection
file: file name of the logical file to be removed from a collection
language:
language of the logical file to be removed from a collection
cics: deletes logical file metadata where the source contains EXEC CICS statements (cics, cics=y, cics=yes, cics=true equate to true. All other
values equate to false.)
sql: deletes logical file metadata where the source contains EXEC SQL statements (sql, sql=y, sql=yes, sql=true equate to true. All other values equate to false.)
dli:
deletes logical file metadata where the source contains DLI statements (dli, dli=y, dli=yes, dli=true equate to true. All other values equate to false.)
A successful DELETE will return a 200 response code.
The logical dependency service enables a user to list logical dependencies based on the query criteria. The service does not allow direct updates to a logical dependency. Therefore there are no PUT/POST/DELETE services. Updates to logical dependencies are done in the context of Collections and Logical Files
id: A numeric id assigned during a POST or PUT of a Collection or Logical Files.
lname: The dependency logical name.
category: The type of the logical dependency.
library:
The library to which this logical dependency belongs.
A GET request without an ID as part of the URL will return all logical dependencies that meet the query criteria. A full list of logical dependencies (no query parameters) is not recommended due to a potential for a large list. The request Accept header
will determine the format (XML or JSON) of the output in the response body.
Example request URLs:
https://localhost:9443/dbb/rest/logicalDependency
https://localhost:9443/dbb/rest/logicalDependency?lname=<lname>&library=<library>&category=<category>
Optional query parameters can be used to limit the amount of data that is returned
lname: limits results to logical dependencies where lname equals the logical dependency logical name.
library:
limits results to logical dependencies where library equals the logical dependency library.
category: limits results to logical dependencies where category equals the logical dependency category.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ |
| application/xml | <logicalDependencies> |
| text/plain | Not Supported |
A GET request with an id is used to read a single logical dependency that corresponds with the id in the URL. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Example request
URL: https://localhost:9443/dbb/rest/logicalDependency/31
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | {"id" : "31", "lname" : "COPY1", "category" : "COPY", "library" : "SYSLIB"} |
| application/xml | <logicalDependency id="31"> |
| text/plain | Not Supported |
A GET request returns all logical files that have a dependency or dependencies that meet the query criteria. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Example request URLs:
https://localhost:9443/dbb/rest/logicalDependency/logicalFile?lname=<lname>&library=<library>&category=<category>&collection={id_or_name}
Return
logical files in a collection that have a dependency that matches the supplied criteria
Query parameters can be used to limit the amount of data that is returned
collection: id or name of a collection. This limits the results to logical files that belong to this collection.
lname:
Identifies a logical dependency where lname equals the dependency lname.
category: Identifies a logical dependency where category equals the dependency category.
library:
Identifies a logical dependency where library equals the dependency library.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <logicalFiles> |
| text/plain | Not Supported |
A GET request returns all logical files that have a dependency identified by the ID in the URL. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Example request URLs:
https://localhost:9443/dbb/rest/logicalDependency/{id}/logicalFile?collection={id_or_name}
Return logical files with a dependency identified by id
Optional query parameters can be used to limit the amount of data that is returned
collection: id or name of a collection. This limits the results to logical files that belong to this collection.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <logicalFiles> |
| text/plain | Not Supported |
A Build Result represents an instance of a build and the resulting artifacts associated with that build (build report, logs, properties, etc).
id: A unique ID assigned by the system to identify individual build result objects.
group: A name used for identifying a group of build results.
label: A name used to identify an instance of a
build result. NOTE: A group and label pair must be unique.
state: An integer representing the state of the build, 0-NEW, 1-PROCESSING, 2-COMPLETE, 3-ABANDONED, or other values defined by the user.
status:
An integer representing the status of the build, 0-CLEAN, 1-ERROR, 2-WARNING, or other values defined by the user.
buildReport: An HTML page used to render the build report data into a consumable format.
buildReportData:
Raw build report data containing information about the files built during a build.
attachment: Zero or more files (compile listings, logs, and other files, etc) attached to this build result. NOTE: JSON format
will use the field name "attachments".
property: zero or more name/value pairs associated with this build result. NOTE: JSON format will use the field name "properties".
created:
timestamp of when the build result was created.
createdBy: Userid used when the build result was created.
lastUpdated: timestamp of when the build result was last updated.
lastUpdatedBy:
>Userid used when the build result was last updated.
owner: The owner of this object. The default value is the creator of the object.
team: The team with access authority to the object. The default value is null.
permission: The type of authority that an owner, team, or individual has to the object. The permission is represented by a three-digit octal number. See Permission Details for more information.
A POST is used to create a Build Result. Use the Content-Type header to indicate the format of the request body. Note that only group, label, state, status, and properties can be set. All other fields will be ignored. Separate POST
requests must be made to add build report/data and each attachment.
Example request URL: https://localhost:9443/dbb/rest/buildResult
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the item created.
Example response URL: https://localhost:9443/dbb/rest/buildResult/1351
| Content-type Header | Example of request body |
|---|---|
| application/json | { |
| application/xml | <buildResult> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A POST is used to create a Build Report associated with a build result. A build report is an HTML page that can render the build report data into a consumable format. Use the Content-Type header to indicate the format of the request body. The request
body is the content of the build report.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReport
Where:
id:
is the unique id number assigned when the build result is created.
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the created artifact.
Example response URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReport
A response code 409(Conflict) is returned if the build result already has a build report. Use DELETE to remove or PUT to update an existing build report.
| Content-type Header | Example of request body |
|---|---|
| text/html is expected | The request body must agree with the content type. Generally, the build report is expected to be an HTML page. |
A POST is used to create Build Report data associated with a build result. The build report data is used by the build report to display information about the files processsed by this build. Use the Content-Type header to indicate the format of the request
body. The request body is the content of the build report data.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReportData
Where:
id:
is the unique id number assigned when the build result is created.
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the created artifact.
Example response URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReportData
A response code 409(Conflict) is returned if the build result already has build report data. Use DELETE to remove or PUT to update existing build report data.
| Content-type | Example of request body |
|---|---|
| application/json is expected | The request body must agree with the content type. Generally, the build report data is expected to be JSON data. |
A POST is used to create an attachment (compile listing, log, etc) to the build result. Use the Content-Type header to indicate the format of the request body. The request body is the content of the attachment.
Example request
URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment/{name}
Where:
id:
is the unique id number assigned when the build result is created.
name: is the name for the new attachment. Duplicate names may exist in a build result but
caution should be used.
A successful POST will return a 201 response code. The response "Location" header will contain the URL of the created artifact.
Example response URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment/2051
Where
2051 is the attachment's id number assigned by the system.
| Content-type Header | Example of request body |
|---|---|
| any content-type | The request body must agree with the content type. |
Adds one or more unique name/value pairs to the build result. Duplicate names are allowed but duplicate name/value pairs are ignored.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/property
Where:
id:
is the unique id number assigned when the build result is created.
A successful POST will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| application/json | { |
| application/xml | <property> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A GET request without a Build Result id as part of the URL is used to get a list of all build result objects. The request Accept header will determine the format (XML or JSON) of the output in the response body.
Example request
URLs:
https://localhost:9443/dbb/rest/buildResult
https://localhost:9443/dbb/rest/buildResult?group=<group>&label=<lable>&property=<property name>&value=<property value>
https://localhost:9443/dbb/rest/buildResult?group=<group>&state=<state>&status=<status>
https://localhost:9443/dbb/rest/buildResult?group=<group>&orderBy=lastUpdated&order=desc
Query parameters can be used to limit the amount of data that is returned
group: limits list to build results with the same group.
label: limits list to build results
with the same label.
property: limits list to build results with an associated property name.
value: limits list to build results with an associated property value.
state:
limits list to build results with a state equal to supplied value. NEW, PROCESSING, COMPLETE, and ABANDONED are also acceptable values.
status: limits list to build results with a status equal to supplied
value. CLEAN, ERROR, and WARNING are also acceptable values.
orderBy: Returns the list sorted on the specified field (id, group, label, created, createdBy, lastUpdated, lastUpdatedBy). Other values are ignored.
order:
Sorting order is ascending(ASC) or descending(DESC). Order defaults to ASC.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <buildResults> |
| text/plain | Not Supported |
A GET request with an ID as part of the URL is used to read the contents of an individual build result object. The request Accept header will determine the format (XML or JSON) of the output in the response body. The URL returned from the POST is used
to perform the GET. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}
id:
is the unique id number assigned when the build result is created.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | { |
| application/xml | <buildResult id="1"> |
| text/plain | Not Supported |
A GET is used to read a Build Report associated with a build result. A build report is an HTML page that can render the build report data into a consumable format. The Content-Type header indicates the format of the response body. The response body
is the content of the build report.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReport
Where:
id:
is the unique id number assigned when the build result is created.
A successful GET will return a 200 response code.
| Accept Header | Example of response body |
|---|---|
| Content-type used on the POST Build Report to create the build report, typically text/html. | The response body must agree with the content type. Generally, the build report is expected to be an HTML page. |
A GET is used to read the Build Report data associated with a build result. The build report data is used by the build report to display information about the files processsed by this build. The Content-Type header indicates the format of the response
body. The response body is the content of the build report data.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReportData
Where:
id:
is the unique id number assigned when the build result is created.
A successful GET will return a 200 response code.
| Content-type Header | Example of response body |
|---|---|
| Content-type used on the Create Build Report Data to create the build report data, typically application/json. | The response body must agree with the content type. Generally, the build report data is expected to be JSON data. |
A GET is used to read a Build Result attachment content. Use List Build Result Attachments to list the attachment metadata. The individual attachment contents are read separately. The Content-Type header
indicates the format of the response body. The response body is the content of the attachment.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment/{a_id}/content
Where:
id:
is the unique id number assigned when the build result is created.
a_id: is the unique id number assigned to the attachment when the attachment was added to
the build result.
A successful GET will return a 200 response code.
| Content-type Header | Example of response body |
|---|---|
| Content-type used on the Create Build Result Attachment to create the attachment. | The response body must agree with the content type. |
A GET request is used to list the metadata for build result attachments. The request Accept header will determine the format (XML or JSON) of the output in the response body. The URL returned from the build result POST is used to perform the GET. The
number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment or https://localhost:9443/dbb/rest/buildResult/{id}/attachment?name=<name>
id: is
the unique id number assigned when the build result is created.
Optional query parameters may also be used to limit the amount of data that is returned
name: limits results to attachments with that name.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <attachments> |
| text/plain | Not Supported |
A GET request is used to list the build result properties. The request Accept header will determine the format (XML or JSON) of the output in the response body. The URL returned from the build result POST is used to perform the GET. The number on the
URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/property or https://localhost:9443/dbb/rest/buildResult/{id}/property?name=<name>
id: is the
unique id number assigned when the build result is created.
Optional query parameters may also be used to limit the amount of data that is returned
name: limits results to properties with that name.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | [ { |
| application/xml | <properties> |
| text/plain | Not Supported |
A GET request is used to list the distinct build result group names. The request Accept header will determine the format (XML, JSON, or plain text) of the output in the response body.
Example request URL: https://localhost:9443/dbb/rest/buildResult/groups
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | ["ADansMA","DansBuild","DansMA"] |
| application/xml | <groups> |
| text/plain | ADansMA |
A GET request is used to list the distinct build result label names. The request Accept header will determine the format (XML, JSON or plain text) of the output in the response body.
Example request URL: https://localhost:9443/dbb/rest/buildResult/labels or https://localhost:9443/dbb/rest/buildResult/labels?group=
Optional query parameters may also be used to limit the amount of data that is returned
group: limits results to labels of build results with group name.
A successful GET will return a 200 response code.
| Accept Header | Example of Response Body |
|---|---|
| application/json | ["ADansMA001","DansMA001","DansMA002","build.20171113.0401"] |
| application/xml | <labels> |
| text/plain | ADansMA001 |
A PUT is used to update a Build Result. Note that only group, label, state, status, and properties can be updated. If other fields are included in the XML or JSON body, they will be ignored. Properties are merged with existing properties.
Updating build report, report data, and attachments must be done via the appropriate update services.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}
Where:
id:
is the unique id number assigned when the build result is created.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| application/json | { |
| application/xml | <buildResult> |
| text/plain | Not Supported |
A PUT is used to update a Build Report associated with a build result. A build report is an HTML page that can render the build report data into a consumable format. Use the Content-Type header to indicate the format of the request body. The request
body is the content of the build report.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReport
Where:
id:
is the unique id number assigned when the build result is created.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| text/html is expected | The request body must agree with the content type. Generally, the build report is expected to be an HTML page. |
A PUT is used to update Build Report data associated with a build result. The build report data is used by the build report to display information about the files processsed by this build. Use the Content-Type header to indicate the format of the request
body. The request body is the content of the build report data.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReportData
Where:
id:
is the unique id number assigned when the build result is created.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| application/json is expected | The request body must agree with the content type. Generally, the build report data is expected to be JSON data. |
A PUT is used to update an attachment to a build result. Only the name property can be update via this API.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment/{a_id}
Where:
id:
is the unique number assigned when the build result is created.
a_id: is the unique number assigned when the attachment was POSTed to the build result.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| application/json | {"name" : "new name"} |
| application/xml | <artifact><name>new name</name></artifact> |
| text/plain | The service will accept a content-type of text/plain with the expectation that the request body is either XML or JSON. |
A PUT is used to update the contents of an attachment (compile listing, log, etc) to the build result. Use the Content-Type header to indicate the format of the request body. The request body becomes the new content of the attachment.
Example
request URL: https://localhost:9443/dbb/rest/buildResult/{id}/attachment/{a_id}/content
Where:
id:
is the unique number assigned when the build result is created.
a_id: is the unique number assigned when the attachment was POSTed to the build result.
A successful PUT will return a 200 response code.
| Content-type Header | Example of request body |
|---|---|
| any content-type | The request body must agree with the content type. |
A build result property cannot be updated. Use Delete Build result Property to remove the old property and Create Build Result Property to create the property with the new value.
A DELETE request is used to delete a build result object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL returned from the POST is used to perform
the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}
Where:
id:
is the unique id number assigned when the build result is created.
A successful DELETE will return a 200 response code.
A DELETE request is used to delete the build report associated with a build result object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL returned
from the POST is used to perform the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReport
Where:
id:
is the unique id number assigned when the build result is created.
A successful DELETE will return a 200 response code.
A DELETE request is used to delete the build report data associated with a build result object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL
returned from the POST is used to perform the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL: https://localhost:9443/dbb/rest/buildResult/{id}/buildReportData
Where:
id:
is the unique id number assigned when the build result is created.
A successful DELETE will return a 200 response code.
A DELETE request is used to remove an attachment from a build result object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL returned from the POST
is used to perform the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL:
https://localhost:9443/dbb/rest/buildResult/{id}/attachment
will delete all attachments of this build result.
https://localhost:9443/dbb/rest/buildResult/{id}/attachment?name=<name>
will
delete all attachments named <name> of this build result.
https://localhost:9443/dbb/rest/buildResult/{id}/attachment/{a_id}
will
delete the attachment with id, a_id, of this build result.
Where:
id: is the unique id number assigned
when the build result is created.
a_id: is the unique id number assigned when the attachment is created.
Optional query parameters may also be used to limit the attachments that are removed.
name: only attachments with this name are removed.
A successful DELETE will return a 200 response code.
A DELETE request is used to remove a property from a build result object. A request body is not expected and will be ignored and no response body is returned. Therefore, no Content-Type or Accept headers are necessary. The URL returned from the POST
is used to perform the DELETE. The number on the URL corresponds with the id attribute in the XML returned by a GET or the id field in the JSON returned by a GET.
Example request URL:
https://localhost:9443/dbb/rest/buildResult/{id}/property
https://localhost:9443/dbb/rest/buildResult/{id}/property?name=<name>
https://localhost:9443/dbb/rest/buildResult/{id}/property?value=<value>
https://localhost:9443/dbb/rest/buildResult/{id}/property?name=<name>&value=<value>
Where:
id:
is the unique id number assigned when the build result is created.
Optional query parameters may also be used to limit the properties that are removed.
No query parameters will remove all properties from the build result
name: only properties with
this name are removed.
value: only the properties with this value are removed.
A successful DELETE will return a 200 response code.
High level objects in the DBB database, like Collection and Build Results, have owner, team, and individual authority permissions. Other objects like logical files and logical dependencies have permissions based on their containing Collection. Likewise, build reports and attachments permissions are controlled by their containing Build Result.
DBB defines three roles that control user authority to read and write DBB objects and authority to access certain REST API. A DBB server user must belong to one of these groups.
DBBAdmins: Has full control and authority over all DBB objects regardless of the object's permissions settings.
DBBUsers: Has authority over DBB objects based on object's owner, team, and individual permission settings.
DBBGuests: Only has read authority over DBB objects if provided via the object's individual authority permissions.
Ownership of a DBB object defaults to the user creating the object. Ownership may be assigned using the owner field during creation (POST) or update (PUT). The owner is granted authority based on the owner permission setting (See Permissions).
A user may belong to a team and will be granted authority to a DBB object based on the team permission setting (See Permissions). The team may be assigned using the team field during creation (POST) or update (PUT). The team defaults to null or empty meaning that no team is assigned. A team is a user registry (i.e. LDAP) group used to assign authority rights to groups of users.
If a user is not the owner of an object nor belongs to a team, they may be granted authority to a DBB object based on the individual permission setting. See Permissions for more details.
Permissions in DBB are assigned using a three digit octal number. The permission setting can be assigned using the permission field during creation (POST) or update (PUT). The first octal digit represents the authority granted to the owner (4=read, 2=write, 6=read and write). The second octal digit represents the team authority and the third octal number represents the authority for everyone else. The default permission is 664 meaning that the owner has read and write permission, the team has read and write permission and everyone else has read permission.