Table of Contents

Date

27 Apr 2017

Attendees

Actions items from previous meetings

• Language Bindings
  
  • 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), Former user (Deleted), Matt Joyce (Deactivated):
    
    • Start a list of the basic functionality bindings should have test for before being considered active. (Possibly Former user (Deleted) too.)
    • Draft list of API endpoints that should be supported by active language bindings.
• REST API Guidelines and Best Practices
  • Former user (Deleted): clear BNY REST API guidelines for external publication.
• Use Cases
  • Former user (Deleted): Progress conversation within Symphony and with Johan Sandersson about how to structure use cases.
  • All: contribute example use cases in the wiki.
• Consuming the Symphony API: 
  • All: Tell Former user (Deleted) which errors/exceptions you're struggling with most so Symphony can prioritize improvement of error handling.
  • All: If you are aware of an open source project that provides a good API for creating bots, tell Former user (Deleted).
  • Former user (Deleted): Talk to Former user (Deleted) about bot deployment work, possibly contributing to Foundation.

Agenda

Meeting notes

Matt Joyce: I’m trying to get feature-complete on the Python bindings and I put out some questions to the list about naming, how to output stuff from the methods, etc.

Peter Monks: I followed up with Matt on the mailing list and hope others will too. I got a couple things out of it, including the idea that we should all separate the raw Swagger layer from the “value-add” layer. Matt, you had proposed terminology for that?

Matt Joyce: The way I’ve implemented it, the bindings really do bind the language to the REST API – it’s a basic exfilitration of REST methods to be used in the language. Then we can build a layer on top with the rest of what we want.

Jon Freedman: To take one example, if you set the active status for a room, what you get back is a little different from what you get from every other method dealing with rooms. The low-level swagger API should replicate that difference, but the higher-level methods should normalize it.

Paul Teyssier: Can you send me information about that inconsistency? We’re trying to move to greater consistency in the REST API.

Jon Freedman: Sure. What can we do about getting access to the latest version of the REST API YAML file so we can keep our Swagger gen updated?

Matt Joyce: We’re trying to convince Symphony to open source it and make it available on an iterative basis rather than one-off, occasionally.

Paul Teyssier: Our intent is to make them open source. Right now, we’re using the same YAML file for internal, private APIs that change rapidly, and for the publicly exposed API. So we need to break them apart so we can make the updated version available with zero overhead for the engineering team. Dan Nathanson owns that and should be done with it on the next sprint.

Peter Monks: What would you recommend happen in the meantime?

Paul Teyssier: I think the best approach would be to open the repo with the YAML files so that people can do the manual separation themselves and get the latest version.

Frank Tarsillo: In the past, I’ve had to update annotations in that file so that inheritance would work. How do we deal with that to avoid unnecessary manual work in the future?

Paul Teyssier: That’s outside my expertise, so I’ll have Dan join next time to discuss it. We’re pushing the limits of what Swagger-gen can do.

Jon Freedman: I think I somewhat disagree—if you want to write a nice, immutable API on top of a REST API, Swagger tells you what to do, you don’t have to build your API with Swagger.

Frank Tarsillo: I agree, but if you are, these are issues you need to deal with.

Jon Freedman: It would help to even just make the API docs publicly available.

Paul Teyssier: The registration required for the API docs is just about keeping tabs on who are users are – think of it as signing up to receive updates about the APIs. We need to keep the community informed since things are moving so quickly.

Jon Freedman: Ok, that’s fine.

Peter Monks: Question for Frank—those inheritance issues, can they be worked around above the raw binding layer?

Frank Tarsillo: I would say it’s a bit difficult to do, because there’s a lot of linkages between the YAML file and what’s generated. To eliminate some of that, you’re writing it out yourself, rather than taking a majority of what’s generated. I’m protecting my SDK from what’s generated via an abstraction layer because we know it’s going to change, and that’s where the heavy lifting is.

Are we considering creating common interface definition at the SDK level rather than just inheriting what comes in from the REST API?

Matt Joyce: It’s an open question.

Frank Tarsillo: I can take a crack at that if others are interested. I was thinking about just creating an API definition from the interface I’ve defined and generated a Swagger YAML file off the back of that.

Matt Joyce: I think that would be a great way to handle it.

Jon Freedman: I think we were planning to standardize around some high level test cases as well…

Matt Joyce: I think that when you get near 1.0 release, you need to be able to show that you support those high-level cases.

Frank Tarsillo: I started to document those, please feel free to send me your thoughts.

Paul Teyssier: In documenting those, we should think about the objects that need to be manipulated and how those are handled.

Frank Tarsillo: Yeah, what I didn’t do is identify the objects that we’re leveraging within those use cases and that’s a good point, we should do that.

Matt Joyce: Yeah, I’ve been focusing on the endpoints.

Frank Tarsillo: That’s where we get into the framework discussions, where you focus on higher-level objects like “chat” and “room,” but here we’re talking about dealing with primitives, maybe with slight modifications. With the standard test cases, we shouldn’t be focused on those high-level framework objects.

Matt Joyce: Yeah, workflows will be different from person-to-person and framework-to-framework, but I can see what you mean.

Peter Monks: Aren’t those all defined in the Swagger gen?

Frank Tarsillo: Yes, but my primitives are not based on those models. I’m hiding those to maintain consistency as the lower-level objects change. They’re so primitive they’re hard to work with, so I’ve created this other layer and that’s really what I’m calling the bindings. Because working with raw generated models and dealing with versions is horrific as a developer.

Paul Teyssier: Are there aspects besides versions that are hard to deal with?

Frank Tarsillo: A few things around directory, identifying users – dealing with UIDs is not helpful, so providing some enrichment in our bindings simplifies working with the platform.

Paul Teyssier: What about authentication, I’ve heard some complaints around that?

Frank Tarsillo: I don’t know what everyone’s complaining about. I’ve created a helper object to deal with the whole token-management process, so maybe that’s the complexity people mean, but what comes out of swagger is pretty straightforward. Can anyone explain the problem?

Paul Teyssier: I think the feedback is that people are unfamiliar with managing certificates.

Frank Tarsillo: Ah, that’s a different story. Yeah, it’s heavy lifting to access Symphony from a development perspective because of the security implementation. If I’d designed it, I probably would have gone the token route rather than client-based cert management, because everyone hates that, and I think token management is the industry standard.

Jon Freedman: We think it’s fine, but we’re small, so I know the guy who maintains the certificates. We registered our internal CA with the Symphony pod and that’s it, we’re good to go. If I want to revoke an account, that’s done external to Symphony.

Frank Tarsillo: We use ping identity internally and have an IDP integrated with Symphony. My preference would be to generate tokens out of that infrastructure and stop dealing with certificates entirely. An infrastructure implementation rather than handholding certificates.

Matt Joyce: On Python, it’s hard to handle certs in a secure manner because Python won’t let you.

Paul Teyssier: Makes sense. Sorry for the tangent.

Frank Tarsillo: I think it’s a great topic but we should have a separate session on that.

Paul Teyssier: I don’t know if we’d change what we have but maybe we could add to it to support other implementations.

Frank Tarsillo: I think the action is to put some definitions in and generate a Swagger YAML file (including interface and objects) off the back end of it and put it in Confluence. Then we can compare those with the raw ones and discuss where to go from there.

Peter Monks: I don’t understand why the Symphony API is forcing users to deal with version information in this way.

Paul Teyssier: Unlike some APIs, we really have very sensitive business-critical apps being built on ours, so we can’t assume that “minor” changes won’t break something critical. With our next release we’ll be more specific about when we change the versions, but it will still be tightly managed, so that customers can be sure things will not change between versions.

Peter Monks: I don’t think Symphony’s unique in supporting business critical use cases. I think the versions should be encapsulated in the YAML file.

Frank Tarsillo: Actually, I kind of appreciate the versioning that Symphony’s put in, I wouldn’t want to hide it.

Peter Monks: It’s not about hiding it. But what others do is leave all versions active when new ones come out, so clients don’t have to do anything when versions change.

Frank Tarsillo: Symphony’s doing that.

Peter Monks: But the YAML file’s not exposing that, if you’re having to do what you’re saying. That could all be encapsulated.

Frank Tarsillo: My purpose is to give you the best API available from the different versions.

Peter Monks: I’m just saying Symphony could do that so we don’t all have to deal with it separately.

Paul Teyssier: Could everyone gather their thoughts on that versioning topic for the next meeting, so we can focus on that? We’re wondering if we’re being too extreme and would like your input.

Peter Monks: I’d suggest soft-pedaling it so we don’t lose momentum on the easier things we’re trying to get done, if that’s a contentious topic.

Paul Teyssier: It’s not contentious, it’s just that we need to have that discussion to be aligned across the community.

Frank Tarsillo: I’ve put in some use cases and would ask others to help.

Action items

• Former user (Deleted): create a CONTRIB to transfer the repository with the REST API YAML files to the Foundation

• Former user (Deleted): create API definitions based on SJC abstracted binding layer and generate a YAML Swagger specification from it

• Aaron Williamson: add action item for next meeting to discuss API versioning issue