Callbacks and code generation

[sapessi]

I've had this contribution in the pipeline for a while. A large part of it is addressed in callbacks. However, I think there is value in setting a standard to expose the API definition a-la OpenID Connect.

Proposal

The sample definitions are below.

• The emitter service (MyCodeRepo) uses a canEmit property in its methods. For example, in my definition I declare that endpoints that make a POST request to /repositories/{repoId}/events should be able to receive the NewCommitEvent type.
• The NewCommitEvent is defined in the eventDefintions section of the Swagger file.
• The request section defines the shape of the request from the event emitter (http verb + body/parameters)
• The response section defines a contract for the event consumer to respect – for example, the emitter here says that 429 responses will cause a retry
• The consumer service (MyPipeline), defines a new events property in one of its paths (in this case /workflows)
• The events property contains a list of events that reference the emitters’ Swagger definition
• The dependency relies on a convention similar to OIDC’s .well-known endpoint where the Swagger is exposed

Outcome

• The emitter will be able to automatically generate a library that creates events – the mechanism to store the subscribers is up to the emitter
• The consumer will be able to auto-generate the server-side APIs to receive the events with the required paths, models and response codes.

What’s missing

• A more formal way for consumers to communicate their endpoint to the emitter – not sure if this is the job of the specs.

Samples - Event emitted (MyCodeRepo)

---
swagger: "2.0"
info:
  version: "1.0"
  title: "MyCodeRepo"
host: "myservice.com"
basePath: "/Prod"
schemes:
- "https"
paths:
  /repositories/{repoId}/events:
    post:
      responses: {}
      security:
        - OAuth: []
      canEmit:
        - !Ref #/eventDefinitions/NewCommitEvent
        
securityDefinitions:
  OAuth:
    type: "apiKey"
    name: "Authorization"
    in: "header"

eventDefinitions:
  NewCommitEvent:
    request:
      method: post
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: false
          schema: !Ref #/definitions/Commit
    response:
      consumes:
        - application/json
      responses:
        200: 
          description: Event received successfully
          schema: !Ref #/definitions/ResponseBody 
          ###### if we expect a response from the client
        429:
          description: Event could not be processed, retry 
          ###### If the client returns this error, the emitter will retry
        400:
          description: Could not process event
                  
definitions:
  Commit:
    type: object,
    required: 
      - CommitId
      - Username
    properties:
      CommitId:
        type: string
      Username:
        type: string
    description: User profile information

Samples - Event consumer (MyPipeline)

---
swagger: "2.0"
info:
  version: "1.0"
  title: "MyPipeline"
host: "mypipeline.com"
basePath: "/Prod"
schemes:
- "https"
paths:
  /workflows:
    events:
      - !Ref 'myservice.com/NewCommitEvent' 
      ###### relies on a well known path like myservice.com/.swagger/definition.yml

[fehguy]

I may be missing something but I believe the current proposed callbacks feature covers this use case from the description point of view. I'll try to move this example into the syntax and we'll see.

[sapessi]

I believe so. I think the biggest difference is in the standard to expose and exchange API definitions between services a-la OIDC (myapi.com/.swagger/definition.yml), which allows for a cross-service reference: !Ref 'myservice.com/NewCommitEvent'. Or, I may have missed the fact that it was there to begin with.

[darrelmiller]

For API description discovery I think we are more likely to head towards the described-by, service-desc link relations (see #724 ) rather than depending on a .well-known URL. Well known URLs are pretty much a last resort when it comes to discovery.

[fehguy]

Sorry for the delay on this--I just did a presentation on callbacks and I believe the intent should handle this use case. You can see that presentation here: https://t.co/1XUELjz5G5

[sapessi]

Thanks @fehguy works for me.

[handrews]

Last comment was "works for me" so I'm closing this :-)