Table of Contents

Date

13 Apr 2017

Attendees

Actions items from previous meetings

• Former user (Deleted): have internal BNY discussion about sharing BNY API best practices guide as starting port for WG document
• Former user (Deleted):
  • Talk to Former user (Deleted) about contributing his MessageML parser for use by Former user (Deleted) in the Symphony Java Client.
  • Add draft language bindings recommendations to Confluence and circulate link via mailing list.
  • Progress conversation within Symphony about how to structure use cases.
• Former user (Deleted):
  • Reproduce the deauthentication(?) error encountered using SJC and send information to Former user (Deleted)
  • Talk to Former user (Deleted) about functionality needed from SJC to support Morgan Stanley's bot-deployment needs
• Former user (Deleted):
  
  • Talk to Former user (Deleted) about bot deployment work, possibly contributing to Foundation.
• All members: 
  • Contribute example use cases in the wiki.
  • Send feedback to Former user (Deleted) on draft recommendations. (Especially Former user (Deleted), Matt Joyce (Deactivated), Former user (Deleted).)
  • If you are aware of an open source project that provides a good API for creating bots, tell Former user (Deleted).

Agenda

Meeting notes

REST API Design Guidelines & Best Practices

Anthony Fabriccino: I’ve been working on getting the BNY REST guidelines into wiki. We’ve updated the guidelines and I have a checkpoint with legal to clear it and then publish it externally on our site and then get it onto the wiki. I have another action with Paul to add a draft around the language bindings and see if there’s any feedback.

Language Bindings subgroup status update

Paul Teyssier: I shared a document with the group a few weeks ago. I didn’t receive a lot of feedback. If it’s useful for the group, we can spend five minutes in this meeting to go over it.

Anthony Fabriccino: Yeah, we have time for that in the agenda. There’s also an action for Dov to talk to Frank about the Symphony Java Client. Has that happened?

Symphony Java Client progress update

Frank Tarsillo: He’s my new best friend. We were trying to communicate with each other over crosspod, and it turns out it was failing. But we’ve spoken over the phone and email and we’ve corrected two issues, one related to duplicate messages sent over the room service, and then some recovery issues on the data feed API endpoint, which needs to be escalated to Symphony LLC because the relevant exception handling is in their app. Dov’s happy now and we’ve also worked together on caching. Happy to have Dov on board the project.

Paul Teyssier: Please let me know about that exception so that we can prioritize it.

Bot framework collaboration update

Anthony Fabriccino: There’s another action about Peter Leong connecting with Dov around bot development. I know Peter has resources internally to work on bot projects, I don’t know if it’s for a Foundation contribution, but it’s Symphony-related so I’ll connect with him today and hopefully post an update to the meeting notes. That’s all the individual action items. There’s some general points that we captured, but we can cover those as we go through the subgroup/activity updates. Those are: language bindings, specification guidelines, and use cases. Johan, can we start with you on use cases?

Use Cases subgroup update

Johan Sandersson: Yes. Unfortunately I’ve been kind of busy and haven’t made much progress as such. There was an email from Dov on some ideas he had on use cases and I asked him to put them in the wiki in the preferred format. I’m not sure why he didn’t and I’ll follow up with him because I want that workflow and format to work. As long as there are meaty use cases in there, we can get working on them. If I don’t get any from others I can add my own, but I don’t want it to be focused solely on my needs.

Anthony Fabriccino: I think going ahead with your own use cases is totally ok. Paul, do you want to go next?

Language Bindings discussion

Paul Teyssier: Is everyone looking at the document? The spirit was to look at the different client projects and to provide some way to help new projects get started, by providing a place for more experienced projects like Java and .NET to share best practices. Also what we are seeing is that many Symphony customers are eager to use language bindings as opposed to going straight for the API. So we’d like to point every new Symphony customer to those language bindings as soon as they’re stable. Right now, we have Java, .NET, Python. Clojure, PHP, and Javascript in various states of completion. If you look at the pattern in the industry, that will probably grow to 10-15.

We put in a user expectations section to define from a user perspective what would be expected in a stable language binding. So we’d like to see what others think about that. The first expectation is that once a client reaches stable status, Symphony LLC is basically supporting those clients because our customers require it. We’re working on a revamp on our product documentation, and in that documentation we’ll start encouraging people to use the SJC and other stable bindings.

Leslie Spiro: Before you get to the language binding, it would be helpful to explain to developers what they can actually do with the API.

Paul Teyssier: Yes, unless you’ve been very deep into it, it’s hard to figure out what you can do easily. In doc redesign, we’re trying to be more precise and up-front about what use cases are supported. We’re partnering with Johan on that. And then there is stale and confusing documentation, and we need to do a spring cleaning of that. I think this will address your needs.

Leslie Spiro: Yes, absolutely.

Paul Teyssier: This is a lot of work, but part of that is that we’ll say, if you’re a Java developer, you should start with the SJC, and we’ll contribute a quick-start guide to the SJC docs. We’re most likely going to start using the SJC internally as well. And once other bindings reach active status, we’ll guide our customers to those and help them learn how to use them practically.

The second expectation for support is functional integrity: the client should support most of the REST API endpoints, and there should be no unsupported or private APIs. And when new endpoints are created, those will be integrated into the bindings reasonably quickly. Then documentation integrity: documentation in the code is aligned with other documentation in its use of terminology, nomenclature, etc. Then quality standards: all public functions of REST API work as expected and API performance is as expected and works in most common deployment scenarios.

We also defined a “readiness checklist” to achieve active status, requiring functional coverage, certain performance minimums, functional integrity, and documentation integrity. And when a client reaches active status, in addition to Foundation outreach, we’ll inform Symphony LLC customers and encourage them to use it.

Leslie Spiro: I would suggest adding that every binding should implement the same Hello World application, and handles connection diagnostics in a defined way.

Frank Tarsillo: That functionality requires a combination of realtime capabilities and interactive request/response. We should be modeling it on what’s been done historically on XMPP and SIP/SIMPLE, which have solved these problems.

Matt Joyce: We’ve just started branching out a separate REST API for webhooks, and there are things about the existing API that makes some of these things difficult, so our approach will be evolving.

Frank Tarsillo: Paul, all of this is great documentation, but I think we need to bring the conversation up one level of abstraction to use cases, like realtime communications, interactive administration, etc.

Anthony Fabriccino: When you say going up a level in use cases, I think that’s what Johan is trying to do with the use cases subgroup.

Frank Tarsillo: Yeah, I think these are all connected. For example if my use case is realtime communications, I can use an interactive or eventing model. They all come back to those same core API capabilities. Or maybe it’s administration: I need to provision a user automatically. What I’m saying is we should tie these use cases back to the requirements via common concepts we see in communications frameworks.

Paul Teyssier: Yeah, that makes sense. To set expectations, I think this document was written late on a weekend when I saw the PHP contrib. I don’t see this document as being very actively maintained, but just a central place to add to, make comments, collaborate, etc.

Jon Freedman: Should you put anything about test coverage in the readiness checklist? I wrote the hubot adapter and one of the hard things is figuring out what to test—should we have a mandated set of use cases that should be tested against?

Frank Tarsillo: One issue is that unit test coverage doesn’t work for collaboration networks. And integration tests have been difficult. The Foundation’s pod doesn’t have crosspod capabilities, so you can’t test that functionality, which is critical.

Paul Teyssier: I’m glad we did this because it surfaces is things like that, and I’m seeing evidence that there’s a need to put some cross-pod capabilities in test pods so that we can do this.  I’ll take that action item—I have some ideas on how to expedite it.

Jon Freedman: I’d say another way to solve this problem is to open source Symphony. I don’t know what the plans are, but I wrote my adapter before we had access to Symphony, so I created a fake web endpoint that you can talk to.

Matt Joyce: I believe there’s already a fake endpoint on the Symphony Developer website, or was at one time.

Frank Tarsillo: Jon, I think you’re right about having a standard set of use cases to test the bindings – send a message, receive presence, etc. That should be another action item: here’s the functionality we want an active client to have tests for.

Matt Joyce: This is kind of the same as testing for, “is this binding complete or working?”

Frank Tarsillo: I didn’t want to raise that yet, but the SJC is more than just bindings—I’ve moved past bindings and into services that help the developer manage communications.

Matt Joyce: Yeah, I think of that kind of functionality as what you build on top of bindings.

Leslie Spiro: I think Frank’s point is more general, that when you’re creating a client for a particular language, you want to provide an abstraction that makes sense in that language. You could imagine defining a set of tasks that you can carry out using the bindings as a minimum set.

Jon Freedman: Yes, there’s a small set of common functionality that every language’s bindings need to handle. Do we want to mandate people to build more complex stuff as a minimum requirement?

Matt Joyce: I think that at that point, you’re building a framework, and the bindings are what you use to do that.

Frank Tarsillo: We’re going into the framework world with SJC which is why we don’t call it bindings, but a client. There’s three levels—raw stuff from LLC, then abstractions of those that I think of as the bindings, then services that are more like a framework. I think we should define what we mean by a binding. A binding is something that wraps the Symphony REST API, and provides an endpoint for a particular language, so the language can leverage that communication in a native way without understanding all the complexity of the API. But you have to change some of the logic to make the API more efficient in that language and for a consumer of that language. I modeled mine off the XMPP Smack API. Which is closer to what you’d see in a communications framework like XMPP or SIP/SIMPLE.

Jon Freedman: I like the way Google defines the philosophy for adding things to Guava: utility times ubiquity. (From the Guava documentation: “A feature is said to have utility when it represents a substantial improvement on the simplest available workaround. A feature has ubiquity when there are a diverse range of use cases for it.”)

Leslie Spiro: I think it’s OK to implement both basic bindings and higher-level abstractions, but I think it’s a good idea to make it possible to use the binding level only, and to be clear which is which.

Frank Tarsillo: I have a diagram on the SJC wiki page that attempts to do this:

Basically we take the Symphony APIs and Swagger gen them into a raw Java interpretation. Then I make endpoints out of that natively, which are crafted specifically to create a feature set I want to expose to Java developers. You don’t have to use anything other than those bindings if you want to create an application. Then I built services on top of that, which leverage the bindings. Then I built the Symphony client module which simplifies all of that. You can use any of these exclusive of the others.

Matt Joyce: My one concern with requiring that basic functionality be implemented only as bindings is that the authentication bits are hard to do in Python cleanly, so I wrote a whole set of methods to do that. I don’t know how that could be done as just a binding, but the rest of this looks right.

Frank Tarsillo: Yeah, the difficulty is always the security measures in place around messaging and simplifying that out in the bindings and services. Did others follow a similar approach to what we did?

Matt Joyce: I took an almost identical approach in Python, although we haven’t implemented as much. You should be able to import the module, get the authentication done simply, then start calling endpoints.

Frank Tarsillo: Is it worth listing out those endpoints people have created to see what they have in common?

Matt Joyce: Return codes and error handling are also huge.

Paul Teyssier: We are very aware that we need to improve error handling, but we’d love feedback from the community on the errors you’re struggling with the most. There’s a long list and we’d like to prioritize.

Frank Tarsillo: Should we list out the endpoints that exist today and what we think there should be? For example, I haven’t done anything with administration, because no one’s asked for it, but we should list those out?

Paul Teyssier: Aren’t the administration API functions more standard CRUD operations?

Frank Tarsillo: Yes, unless you add efficiency as we’ve done with messaging endpoints. For example, if it takes 5 endpoint calls to make a user, we might implement that as one endpoint in the client.

Paul Teyssier: There might be less need for that with the lower-level administration endpoints.

Frank Tarsillo: That’s fair, I haven’t looked at them, but that’s where I see the client differing from the Symphony API endpoints.

Action items

• Former user (Deleted): clear BNY REST API guidelines for external publication.
• Former user (Deleted) will look into how to enable limited cross-pod capabilities on the Foundation's test pod and others to make integration testing possible.
• Former user (Deleted) (and possibly Former user (Deleted), Former user (Deleted), and Matt Joyce (Deactivated)): start a list of the basic functionality bindings should have test for before being considered active.
• Former user (Deleted), Former user (Deleted), Matt Joyce (Deactivated): draft list of API endpoints that should be supported by active language bindings.
• All: tell Former user (Deleted) which errors/exceptions you're struggling with most so Symphony can prioritize improvement of error handling.