Enterprise Social Messaging Environment (ESME)
  1. Enterprise Social Messaging Environment (ESME)
  2. ESME-14

Redesign, rework, write unit tests for, and fully document API

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: Backlog
    • Fix Version/s: Release 1.1
    • Component/s: Server
    • Labels:
      None

      Description

      This issue is now an umbrella issue for all updates to the /api2 API endpoint. Most work should be tracked as subtasks or mapped issues. Please see http://cwiki.apache.org/confluence/display/ESME/API+2.0+-+Design to track the current design of the /api2 endpoint.

      1. new_api_initial_diff.diff
        16 kB
        Ethan Jewett
      2. api2_update_2009_10_30.diff
        32 kB
        Ethan Jewett
      3. api2_update_2009_11_07.diff
        40 kB
        Ethan Jewett
      4. api2_update_2009_11_14.diff
        46 kB
        Ethan Jewett
      5. api2_update_2009_11_19.diff
        9 kB
        Ethan Jewett
      6. API2.scala
        17 kB
        Dick Hirsch
      7. org.apache.esme.api.Api2SpecsAsTest.txt
        8 kB
        Dick Hirsch
      8. API2Test.scala
        3 kB
        Dick Hirsch
      9. api2_update_2009_11_27.diff
        39 kB
        Ethan Jewett
      10. esme2java.jar
        7 kB
        Daniel Koller

        Issue Links

          Activity

          Hide
          Ethan Jewett added a comment -

          All sub-tasks are now closed or converted into full issues.

          Show
          Ethan Jewett added a comment - All sub-tasks are now closed or converted into full issues.
          Hide
          Hudson added a comment -

          Integrated in ESME #34 (See http://hudson.zones.apache.org/hudson/job/ESME/34/)
          [] Redesign, rework, write unit tests for, and fully document API
          Patch from Ethan Jewett applied

          Show
          Hudson added a comment - Integrated in ESME #34 (See http://hudson.zones.apache.org/hudson/job/ESME/34/ ) [] Redesign, rework, write unit tests for, and fully document API Patch from Ethan Jewett applied
          Hide
          Ethan Jewett added a comment -

          Hi Daniel,

          As mentioned on Twitter, but here for posterity ...

          Wow! Very cool. Thank you for working on this. I fairly desperately need feedback from those trying to implement clients on the api2 endpoint.

          With regards to your comments:

          • We don't currently have any API2 methods which are public (do not require auth). However, we very well could and I would be happy to add them if they make sense and you or someone else will use them. Just let me know. We should probably also discuss additions like this on the mailing list. I'd be happy to broach the topic.
          • On other means of authorization: Yes, we need a modified approach, preferably to bring our token-based auth in line with an existing standard like OAuth. I'm sort of waiting for the OAuth 2.0 effort to settle down into an implementor's draft before I try to foist a change in the authorization technique on the API2. I'd like to only change it once (API3 anybody?) For now I strongly recommend that people installing ESME servers require all connections to use SSL/TLS (HTTPS). I am under the impression that we can't do this on Stax for various reasons.

          Is the code for your client available? May I recommend Github for making it public?

          Ethan

          Show
          Ethan Jewett added a comment - Hi Daniel, As mentioned on Twitter, but here for posterity ... Wow! Very cool. Thank you for working on this. I fairly desperately need feedback from those trying to implement clients on the api2 endpoint. With regards to your comments: We don't currently have any API2 methods which are public (do not require auth). However, we very well could and I would be happy to add them if they make sense and you or someone else will use them. Just let me know. We should probably also discuss additions like this on the mailing list. I'd be happy to broach the topic. On other means of authorization: Yes, we need a modified approach, preferably to bring our token-based auth in line with an existing standard like OAuth. I'm sort of waiting for the OAuth 2.0 effort to settle down into an implementor's draft before I try to foist a change in the authorization technique on the API2. I'd like to only change it once (API3 anybody?) For now I strongly recommend that people installing ESME servers require all connections to use SSL/TLS (HTTPS). I am under the impression that we can't do this on Stax for various reasons. Is the code for your client available? May I recommend Github for making it public? Ethan
          Hide
          Daniel Koller added a comment -

          ESME 2 Java

          Built in functionality:

          • logon to an esme instance,
          • post a message

          Dependencies:

          • former apache commons http-client library is required
          • ESME instance has to support ESME API2

          Approach:

          • create an ESMEServer instance and
          • use postMessage () to send a message.
          Show
          Daniel Koller added a comment - ESME 2 Java Built in functionality: logon to an esme instance, post a message Dependencies: former apache commons http-client library is required ESME instance has to support ESME API2 Approach: create an ESMEServer instance and use postMessage () to send a message.
          Hide
          Daniel Koller added a comment -

          First comments on API2 after starting an ESME Java Library:

          • Auth now works with tokens... this brings up two questions:
            • Do we have API2 methods which do not require authentication? (public timeline?)
            • Can/should we already support other means ... (oAuth etc.) (maybe i am not completely up to date what has been discussed)

          "Add Message": we can add tags either inline with the text oder with separate parameter..I think having them in the message serves our goals completely.

          Thats for now,

          Show
          Daniel Koller added a comment - First comments on API2 after starting an ESME Java Library: Auth now works with tokens... this brings up two questions: Do we have API2 methods which do not require authentication? (public timeline?) Can/should we already support other means ... (oAuth etc.) (maybe i am not completely up to date what has been discussed) "Add Message": we can add tags either inline with the text oder with separate parameter..I think having them in the message serves our goals completely. Thats for now,
          Hide
          Hudson added a comment -
          Show
          Hudson added a comment - Integrated in ESME #25 (See http://hudson.zones.apache.org/hudson/job/ESME/25/ )
          Hide
          Ethan Jewett added a comment -

          This patch does the following:

          1. Reaches nearly full test coverage for all existing API2 methods

          2. Changes response codes to be correct when the request isn't successful (e.g. 403 not 200)

          3. Internally switches to using a uniform Rack-like response format for API methods, which is then implicitly converted to a Lift response type, cutting down on a lot of the complexity and mysteriousness of the ApiHelper class.

          Show
          Ethan Jewett added a comment - This patch does the following: 1. Reaches nearly full test coverage for all existing API2 methods 2. Changes response codes to be correct when the request isn't successful (e.g. 403 not 200) 3. Internally switches to using a uniform Rack-like response format for API methods, which is then implicitly converted to a Lift response type, cutting down on a lot of the complexity and mysteriousness of the ApiHelper class.
          Hide
          Hudson added a comment -

          Integrated in ESME #20 (See http://hudson.zones.apache.org/hudson/job/ESME/20/)
          [] Redesign, rework, write unit tests for, and fully document API
          Patch from Ethan Jewett applied

          Show
          Hudson added a comment - Integrated in ESME #20 (See http://hudson.zones.apache.org/hudson/job/ESME/20/ ) [] Redesign, rework, write unit tests for, and fully document API Patch from Ethan Jewett applied
          Hide
          Dick Hirsch added a comment -

          Current files + test results

          Show
          Dick Hirsch added a comment - Current files + test results
          Hide
          Dick Hirsch added a comment -

          Got an error during the tests after the patch:

          Test set: org.apache.esme.api.Api2SpecsAsTest
          -------------------------------------------------------------------------------
          Tests run: 3, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 5.093 sec <<< FAILURE!
          API2 should Attempt to create session with an invalid token returns 400 response Time elapsed: 0 sec <<< FAILURE!
          org.specs.runner.UserError: '200' is not equal to '400'.

          I'm attaching the surefire test report and the API2.scala file.

          Show
          Dick Hirsch added a comment - Got an error during the tests after the patch: Test set: org.apache.esme.api.Api2SpecsAsTest ------------------------------------------------------------------------------- Tests run: 3, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 5.093 sec <<< FAILURE! API2 should Attempt to create session with an invalid token returns 400 response Time elapsed: 0 sec <<< FAILURE! org.specs.runner.UserError: '200' is not equal to '400'. I'm attaching the surefire test report and the API2.scala file.
          Hide
          Ethan Jewett added a comment -

          This patch does two things:

          1. Updates the API2 tests to use David's new Lift TestKit, and adds tests for session logins (one of which fails because the response code for a failed login is wrong)

          2. Changes the api2/user/messages behavior to align with the design documented on the wiki (http://cwiki.apache.org/confluence/display/ESME/API+2.0+-+Design) and discussed on the dev mailing list.

          Show
          Ethan Jewett added a comment - This patch does two things: 1. Updates the API2 tests to use David's new Lift TestKit, and adds tests for session logins (one of which fails because the response code for a failed login is wrong) 2. Changes the api2/user/messages behavior to align with the design documented on the wiki ( http://cwiki.apache.org/confluence/display/ESME/API+2.0+-+Design ) and discussed on the dev mailing list.
          Hide
          Hudson added a comment -

          Integrated in ESME #11 (See http://hudson.zones.apache.org/hudson/job/ESME/11/)
          [] Redesign, rework, write unit tests for, and fully document API
          Patch from Ethan Jewett applied
          Forgot this file

          Show
          Hudson added a comment - Integrated in ESME #11 (See http://hudson.zones.apache.org/hudson/job/ESME/11/ ) [] Redesign, rework, write unit tests for, and fully document API Patch from Ethan Jewett applied Forgot this file
          Hide
          Ethan Jewett added a comment -

          This patch makes a lot of changes. The end result should be:

          1. The API2 tests should now run

          2. The comet-based message interface is now added back at api2/user/messages?timeout=10 (or any other number - eventually this will define the timeout length)

          3. The message response format has been updated.

          Specific changes:

          1. Updated MsgParserSpecs and Api2Specs to properly start and stop the JettyTestServer using specs before/after definitions for setup and teardown of the environment.

          2. Updated Message.scala to make it possible to get at the body and metadata of a message using a Message object.

          3. Refactored out the XML helper code in API2 into a trait.

          4. Updated API2.scala extensively to accomplish changes (2) and (3) above.

          Show
          Ethan Jewett added a comment - This patch makes a lot of changes. The end result should be: 1. The API2 tests should now run 2. The comet-based message interface is now added back at api2/user/messages?timeout=10 (or any other number - eventually this will define the timeout length) 3. The message response format has been updated. Specific changes: 1. Updated MsgParserSpecs and Api2Specs to properly start and stop the JettyTestServer using specs before/after definitions for setup and teardown of the environment. 2. Updated Message.scala to make it possible to get at the body and metadata of a message using a Message object. 3. Refactored out the XML helper code in API2 into a trait. 4. Updated API2.scala extensively to accomplish changes (2) and (3) above.
          Hide
          Hudson added a comment -

          Integrated in ESME #2 (See http://hudson.zones.apache.org/hudson/job/ESME/2/)
          [] Redesign, rework, write unit tests for, and fully document API
          Patch from Ethan Jewett applied

          Show
          Hudson added a comment - Integrated in ESME #2 (See http://hudson.zones.apache.org/hudson/job/ESME/2/ ) [] Redesign, rework, write unit tests for, and fully document API Patch from Ethan Jewett applied
          Hide
          Ethan Jewett added a comment -

          Can we change the title and description of this issue? Something like "Redesign, rework, write unit tests for, and fully document API". I think we've agreed that while RESTful design principles are going to inform the approach for some parts of the API, they are not appropriate for all parts of the API.

          Show
          Ethan Jewett added a comment - Can we change the title and description of this issue? Something like "Redesign, rework, write unit tests for, and fully document API". I think we've agreed that while RESTful design principles are going to inform the approach for some parts of the API, they are not appropriate for all parts of the API.
          Hide
          Ethan Jewett added a comment -

          This diff makes the following updates:

          1. Further updates to the resource tree structure
          2. Beginning to update the response formats
          3. Set up structure for spec-tests of the API (and wrote two placeholder tests)

          Should be able to apply it to the current truck.

          Show
          Ethan Jewett added a comment - This diff makes the following updates: 1. Further updates to the resource tree structure 2. Beginning to update the response formats 3. Set up structure for spec-tests of the API (and wrote two placeholder tests) Should be able to apply it to the current truck.
          Hide
          Ethan Jewett added a comment -

          Current checked in api2 won't work because the boot.scala file does not prepend the Req dispatching from the API2 object. Please apply this diff to the current trunk.

          Other functionality is basically the same, though this file includes a total move-around of the API2.scala file and some initial refactoring moves...

          Show
          Ethan Jewett added a comment - Current checked in api2 won't work because the boot.scala file does not prepend the Req dispatching from the API2 object. Please apply this diff to the current trunk. Other functionality is basically the same, though this file includes a total move-around of the API2.scala file and some initial refactoring moves...
          Hide
          Ethan Jewett added a comment -

          Actually .... the patch doesn't create the new branch. The new branch must be created before the patch is applied. I think. It's been a while since I've used Subversion (mostly Git these days for me).

          Show
          Ethan Jewett added a comment - Actually .... the patch doesn't create the new branch. The new branch must be created before the patch is applied. I think. It's been a while since I've used Subversion (mostly Git these days for me).
          Hide
          Ethan Jewett added a comment -

          This is an initial commit that creates a new branch called "new_api", creating an /api2/ endpoint with a more RESTful structure where appropriate. This could be added to the trunk without interfering with the existing API, but I'd like to get it in and a branch seems like the safest place to do this.

          Show
          Ethan Jewett added a comment - This is an initial commit that creates a new branch called "new_api", creating an /api2/ endpoint with a more RESTful structure where appropriate. This could be added to the trunk without interfering with the existing API, but I'd like to get it in and a branch seems like the safest place to do this.
          Hide
          Ethan Jewett added a comment -

          Dick, I'm going to try to break some of this out into sub-tasks, starting with agreeing on a RESTful design for the API.

          Show
          Ethan Jewett added a comment - Dick, I'm going to try to break some of this out into sub-tasks, starting with agreeing on a RESTful design for the API.

            People

            • Assignee:
              Ethan Jewett
              Reporter:
              Dick Hirsch
            • Votes:
              1 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Time Tracking

                Estimated:
                Original Estimate - 8h
                8h
                Remaining:
                Remaining Estimate - 8h
                8h
                Logged:
                Time Spent - Not Specified
                Not Specified

                  Development