== Client Application Development [[authentication]] === Authentication Almost every Helix Web Services method requires authentication. We provide a simple token-based authentication scheme, similar to what you might use with OAuth. You must authenticate using our <<POST /api/hws/v16.1/login>> method, then use that ticket value as the `Authorization` header value. [[error_responses]] === Error Conventions Upon success, methods of Helix Web Services return the 200 HTTP status code. If your authentication token is not valid, you will receive the status code 403. You will then need to update the login token (using <<POST /api/hws/v16.1/login>>). HTTP status code 401 will likely originate from the Helix Versioning Engine. In this case, we provide information to the client application via a JSON object. This object will contain three main properties: [cols="2*", options="header"] |=== | Property | Description | `MessageCode` | A numeric ID for the problem, typically defined by the Helix Versioning Engine. Should be the same value as http://www.perforce.com/perforce/r15.1/manuals/p4api/chapter.methods.html#error.getgeneric[Error::GetGeneric()]. | `MessageSeverity` | Mirrors the severity levels of http://www.perforce.com/perforce/r15.1/manuals/p4api/chapter.methods.html#error.getseverity[Error::GetSeverity()]. Generally going to be 3 or 4. | `MessageText` | Informational text that will likely not be localized appropriately for the user. |=== When 500 errors happen, a serious problem has occurred, which may mean an important subsystem is compromised. Do not expect a response body. The problem will have to be investigated on the server side. Your client should not attempt further communication with Helix Web Services.
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #17 | 19601 | swellard | Refactor REST path - doc tweaks | ||
| #16 | 19012 | tjuricek | Revised Java client SDK, added ApiClient reference, restructured documentation. | ||
| #15 | 19002 | tjuricek |
Improve API to interact with multiple p4ds. The configuration now requires an explicit setting of what P4Ds HWS can talk to via the 'P4D config dir', where there's a file indicating connection settings per p4d, and importantly, an ID. This is the "server ID" referenced everywhere. Most methods now require a server ID to indicate which p4d to manipulate. In the future, it's likely we will interact with *multiple* p4d instances on some services. This completely removes the ability to run HWS as a kind of an "open proxy" to whatever p4d you want. Given the nature of the change and the lack of priority, we've removed Helix Cloud testing and disabled several methods from their "Helix Cloud" implementation. These will be relatively easy to bring back, we'll just need a new method from Raymond that lists the "allowed server IDs" that map to the HWS configured server IDs for a particular user. Another notable aspect of this change is the use of JSON Web Token to create our authentication key. We associate this key with an in-memory "session" that contains the P4D tickets we use to authenticate users. The JWT token, by default, is assigned a timeout, which allows HWS to block further access to underlying servers without having to interact with multiple auth backends. If any backend fails with that session, the user will get a 403. If you disable the timeout, you'll need to ensure your clients clear out sessions. |
||
| #14 | 18876 | tjuricek | Document the requirement is Java 8 not java 7 | ||
| #13 | 18875 | tjuricek | Correct the type of the model and comments in the Java example code. | ||
| #12 | 18818 | tjuricek | Python Client SDK for Helix Web Services | ||
| #11 | 18811 | tjuricek | Initial PHP client SDK for Helix Web Services. | ||
| #10 | 18810 | tjuricek |
First-pass at JavaScript client SDK. JavaScript requires Node with Gulp to "browserfy" the library. It's the easiest way I found to use the swagger-js project; bundle up a wrapping method. There is no JavaScript reference guide. The swagger-js doesn't really document what they do very well, actually. Overall I'm not particularly impressed by swagger-js, it was hard to even figure out what the right method syntax was. We may want to invest time in doing it better. This required setting CORS response headers, which are currently defaulted to a fairly insecure setting. |
||
| #9 | 18788 | tjuricek | Correct references to URL paths in asciidoc and add minor release number to default version string. | ||
| #8 | 18695 | tjuricek | Revise client guide to indicate new shorter URL paths. | ||
| #7 | 18693 | tjuricek |
Move from swagger2markdown project to custom asciidoc generator. This gives us flexibility to do include the context path, for example, or alter the output fairly easily. While StringTemplate is a little tricky to get to know, it works pretty well for our needs, and offers a lot more flexibility for reorganization later. Note: I might change the status method to be version-specific, but in the future, we'll have a method "what versions do you support" which will *not* be version-specific. |
||
| #6 | 18681 | tjuricek | Fix link references to the revised URLs | ||
| #5 | 18605 | tjuricek |
Document a simplified method for obtaining the Java client SDK handle. The client SDK is included as a part of the distribution. Javadoc is included in a subdirectory and hosted directly. A stupid simple HTML page was added by default to give people something to access right after installation. |
||
| #4 | 18551 | tjuricek |
Switch to using swagger-based HTTP methods. Remove old java_client. The swagger documentation generates asciidoc, which is included in the current user guide. We lose some control over the formatting. |
||
| #3 | 17339 | tjuricek |
Removed obsolete documentation no longer relevant to JVM-based installation, and created framework for new installation. I do not have exact details on the new system just yet, but I know we'll want the PDF as part of the installation. |
||
| #2 | 17327 | tjuricek | Fixing broken link references uncovered by the DocBook processing chain. | ||
| #1 | 17323 | tjuricek |
Revise the documentation to use the JVM-based asciidoctor. This will generate the DocBook XML. I'm still ironing out exactly what the CD process is here. |
||
| //guest/perforce_software/helix-web-services/main/source/doc/04_clientprog.asc | |||||
| #4 | 17090 | tjuricek |
Revised documentation based on edits received (on paper). Removed Helix Web Services ruby client references, since there is no publication plan for this API. |
||
| #3 | 16095 | tjuricek | Shorten /helix_versioning_engine URLs to /p4 | ||
| #2 | 15686 | tjuricek | Removed Qt SDK (will be maintained with Helix Sync), updated README | ||
| #1 | 15622 | tjuricek |
Move source code to 'source/' subdirectory of branch. build/ will remain where it is. |
||
| //guest/perforce_software/helix-web-services/main/doc/04_clientprog.asc | |||||
| #11 | 15447 | tjuricek |
Add simple Example application to list "projects" in a HVE instance. Qt's a little weird to follow, so I may have to find a different kind of example to write. It does work, however. |
||
| #10 | 15435 | tjuricek |
Add proposed HTTP methods for Helix Sync. It's a little unclear to me why you would need a local root directory to create the shared shelving changelist for a particular project (and user). So I didn't add that. |
||
| #9 | 15423 | tjuricek |
Revised HWS Qt API. This is a major revision of the API, which removes most of the "typed" data, replacing it with a more generic "executeMethodDone" callback. The main benefit here is to allow the API to interop with different versions of p4d, and not restrict the methods it can call. We may add more helpers in the future. |
||
| #8 | 15257 | tjuricek |
Added stress test, corrected per-request header config. Apparently using underscores is a "special" mechanism for HTTP headers, and requires adjusting nginx to allow such things. Might as well just recommend using hyphens, which get converted to underscores anyway. The current test just hits a listing of 20000 files against p4play. Returns a 2.5 MB response, which doesn't seem to cause problems (yay). |
||
| #7 | 15240 | tjuricek |
Set api level via request path on all Helix Versioning Engine methods. This will allow migration of applications to different P4D versions. Our internal methods (like project API) should attempt to handle backward compatibility similarly. P4WEBAPI-118 |
||
| #6 | 15132 | tjuricek | Provde a basic submit -e mechanism on classic perforce workspaces. | ||
| #5 | 15078 | tjuricek |
clients spec method revisions Updated some other documentation. |
||
| #4 | 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. |
||
| #3 | 15053 | tjuricek |
Revise the client API to use the new login method. The current specs will need to be revised since data normalization is moving out of the server and into the client. |
||
| #2 | 15042 | tjuricek | Document error conventions. | ||
| #1 | 15038 | tjuricek | Document 'login' auth method and client programming overview. | ||
| //guest/perforce_software/helix-web-services/main/doc/03_clientprog.asc | |||||
| #3 | 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. |
||
| #2 | 14980 | tjuricek |
Starting to make revisions to the Asciidoc guide. These are just revisions to the preable sections. |
||
| #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. |
||