=== Branches [[get_helix_versioning_engine_v1_branches]] ==== `GET /helix_versioning_engine/v1/branches` Lists available branches in the system. The resources of this list are summaries of branches in the system. For more details of each branch, append the `branch` property the end of this URL. There are no other parameters to this method. This method requires authentication. See <<_perforce_web_api_authentication>> ===== Response JSON Object Returns the result of the `p4 -ztag branches` command. For more field information refer to the command reference. [cols="4*", options="header"] |=== | Parameter | Description | Type | Required | Branch | The branch name and primary ID | string | Yes | Owner | The Perforce login of the user that owns this branch | string | Yes | Options | The options of the branch specification | string | Yes | Description | The branch description | string | Yes | Update | The date the branch mapping was last changed. | number | Yes | Access | The date the branch mapping was last accessed. | number | Yes |=== ====== Example Our standard authenticated request format for listing branches: GET /v1/branches HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Here's an example of a list with two branches in the response: HTTP/1.1 200 OK Content-Type: application/json [{ "Branch": "yagg-main", "Update": 1410907712, "Access": 1410907712, "Owner": "super", "Options": "unlocked", "Description": "Maintains a path from a development area to a main area.\n" }, { "Branch": "secondary-dev", "Update": 1410907541, "Access": 1410907111, "Owner": "jdoe", "Options": "unlocked", "Description": "Updates project Secondary's development area.\n" }] ===== `POST /v1/branches` Creates a new branch specification. Upon success, this will return a 303 redirect to the new branch specification resource that has been created. If the branch already exists, this method will replace the existing branch completely. This method requires authentication. See <<_perforce_web_api_authentication>>. ====== Parameters [cols="5*", options="header"] |=== | Parameter | Description | Type | Parameter Type | Required | Branch | The name of the branch | string | body | Yes | Owner | The Perforce login of the user that owns the branch | string | body | No | Description | A textual description of this branch | string | body | No | View | How different paths in the depot should relate to each other. Each string in the array contains a source and target end of the mapping. See the user guide for more information. | array | body | Yes |=== ====== Example We'll create a simple branch my-project-main that maps `//depot/main/my-project/...` to `//depot/dev/my-project/...`. POST /v1/branches HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Branch": "my-project-main", "Description": "Branch my project from main to dev.\n", "View": ["//depot/main/my-project/... //depot/dev/my-project/..."] } The return value should be a redirect to the details page of the new branch. HTTP/1.1 303 Found Location: http://example.com/p4/v1/branches/my-project-main You may need to recall that the URL returned by a 303 response should be accessed via GET, and not via POST. ===== `GET /v1/branches/[branch]` Return branch details. This method requires authentication. See <<_perforce_web_api_authentication>>. ====== Parameters [cols="5*", options="header"] |=== | Parameter | Description | Type | Parameter Type | Required | branch | The branch name. | string | path | Yes |=== ====== Response Data Returns the result of `p4 -ztag branch [branch name].` For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field. [cols="4*", options="header"] |=== | Parameter | Description | Type | Required | Branch | The name of the branch | string | Yes | Owner | The Perforce login of the user that owns the branch | string | Yes | Description | A textual description of this branch | string | Yes | View | How different paths in the depot should relate to each other. Each string in the array contains a source and target end of the mapping. See the user guide for more information. | array | Yes | Update | The date the branch mapping was last changed. | number | Yes | Access | The date the branch mapping was last accessed. | number | Yes |=== ====== Example Here is an example request for the branch yagg-main. This is a fairly simple branch, containing only one view mapping. GET /v1/branches/yagg-main HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj And the typical JSON response: HTTP/1.1 200 OK Content-Type: application/json { "Branch": "yagg-main", "Update": 1410907712, "Access": 1410907712, "Owner": "super", "Description": "Maintains a path from a development area to a main area.\n", "Options": "unlocked", "View": ["//depot/yagg/... //depot/main/yagg/..."] } ===== `PATCH /v1/branches/[branch]` Update branch specifications. Only the specified parameters in the body will be changed. This method requires authentication. See <<_perforce_web_api_authentication>>. ====== Parameters [cols="5*", options="header"] |=== | Parameter | Description | Type | Parameter Type | Required | branch | The name of the branch | string | path | Yes | Owner | The Perforce login of the user that owns the branch | string | body | No | Description | A textual description of this branch | string | body | No | View | How different paths in the depot should relate to each other. Each string in the array contains a source and target end of the mapping. See the user guide for more information. | array | body | No |=== ====== Example Here we'll update the description of the existing branch my-project-main. PATCH /v1/branches/my-project-main HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj Content-Type: application/json { "Description": "The updated my-project-main description.\n" } The response will only contain the normal HTTP status information. HTTP/1.1 200 OK ===== `DELETE /v1/branches/[branch]` Removes the branch specification. This method requires authentication. See <<_perforce_web_api_authentication>>. ====== Parameters [cols="5*", options="header"] |=== | Parameter | Description | Type | Parameter Type | Required | branch | The branch name. | string | path | Yes |=== ====== Example Delete the branch `my-project-main`: DELETE /v1/branches/my-project-main HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj The response will only contain the normal HTTP status information. HTTP/1.1 200 OK
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#10 | 15144 | tjuricek |
Setup stream spec tests and documentation. Also revised the documentation folder http_p4_web_api -> helix_versioning_engine |
||
#9 | 15110 | tjuricek | Revise changes methods for new p4 connection handling, add server specs, remove model references in client, and update asciidoc documentation. | ||
#8 | 15090 | tjuricek |
Update _proposed_ API for project services. This is *very likely* to change, and will not be implemented until reviewed. |
||
#7 | 15078 | tjuricek |
clients spec method revisions Updated some other documentation. |
||
#6 | 15077 | tjuricek |
Add new 'model' technique, revised branch spec operations, test Auth::Middleware. The Ruby client now does *not* strictly type anything, but extends OpenStruct with helper methods to help deal with inconsistent data formats. See the OpenModel class documentation for more details. The Auth::Middleware class is also *finally* implemented as well. This does not take into account all possible variations of server behavior (yet), but that will happen in follow-up work. |
||
#5 | 15038 | tjuricek | Document 'login' auth method and client programming overview. | ||
#4 | 15032 | tjuricek |
Starting config and doc revisions. System is now broken while revisions underway. Configuration of the p4d connection is now done via a single HWSSettings middleware object injected into the Rack env. The HWSP4Cleanup middleware now cleans up any p4 injected into the Rack env. The Auth::App class now mostly just contains one method to generate a p4 ticket. /auth/v1/login. Added yard documentation for the main project. Yard docs have been reconfigured to dump into build/ directories. This should probably be done with each release. Hm... The top level rake file contains a task, 'all:doc', to update our documentation. This should probably be run for each checkin. Hm... Specs are now using Rack::Test on top of a 'live' p4d. I'd suggest you still use the p4util mechanism, which now dumps to a /tmp folder, so we can safely add P4IGNORE rules back into your local .p4config file. Old 'perforce' application now called 'helix_versioning_engine'. Removing cache data. Helix Sync may be slow. It may also get axed. We'll see. |
||
#3 | 14182 | tjuricek | Asciidoc conversion of the changes HTTP guide | ||
#2 | 13612 | tjuricek | Update deployment guide, switch built documentation to asciidoc, remove unused packaging script for p4_web_api | ||
#1 | 13555 | tjuricek |
Starting Asciidoc conversion of documentation. Removed the "Shared Quality" document, that basically is online now at: https://confluence.perforce.com:8443/display/PWS/Quality+Assurance Adding some topology graphviz images used for online documentation. |