Demonstrate Microcks Mocking #21

philsturgeon · 2024-06-26T12:05:23Z

This branch aims to get the Train Travel API working with Microcks as smoothly as possible, with good dynamic responses and minimal errors showing up in the Spectral ruleset.

philsturgeon · 2024-11-05T14:03:36Z

@paulRbr @scharrier I have updated the microcks pull request as it had a few unrelated changes, so you can clearly see what needs to be done in order for a OpenAPI to work with both Bump.sh and Microcks.

Microcks currently requires a) named examples, and b) variables in the response examples in order to reuse request parameters.

The names examples show up the same as usual, but they do make the OpenAPI a little more clunky.

The variables in the response show up literally in Bump.sh and this of course makes no sense to the user.

So, questions:

Are we ok with the Train Travel API using this slightly more clunky OpenAPI for named examples? If not... I had mentioned to Microcks about supporting single example instead of only working with named pairs, but named pairs can be very powerful if used correctly. If we need Microcks to roll out a new feature before pushing collaboration this could be a blocker.
Are we ok with the Train Travel API demo showing these variables in there, or should we try and avoid that somehow.

A. Bump.sh Docs adds functionality to reuse values from the request to populate those variables and make for a heck of a powerful feature nobody else currently has.
B. We use overlays to add these examples and have a second Microcks-enabled OpenAPI document that is hosted elsewhere, which we then make available for the microcks team to pull in.

Probably B, I thought of that mid writing this all out. 😆

Still, thoughts on this would be welcome when you have a moment.

openapi.yaml

lbroudoux · 2024-11-05T16:08:21Z

Are we ok with the Train Travel API using this slightly more clunky OpenAPI for named examples? If not... I had mentioned to Microcks about supporting single example instead of only working with named pairs, but named pairs can be very powerful if used correctly. If we need Microcks to roll out a new feature before pushing collaboration this could be a blocker.

I tried this after our conversation but relying on single default example raise a lot of other question in the case of multiple response codes, response formats and so on. It works with very basic API (1 input/1 output) but doesn't work with realistic ones.

B. We use overlays to add these examples and have a second Microcks-enabled OpenAPI document that is hosted elsewhere, which we then make available for the microcks team to pull in.

This is definitely possible to move those "advanced" examples using expressions into another OpenAPI file. APIVersion your declare on the Microcks Hub can reference many artifacts and these ones will be merged during the import. So expressions won't "pollute" the OpenAPI spec.

grossyoan · 2024-11-18T19:19:56Z

Hey!

Friendly ping @scharrier @paulRbr 🙏

@paulRbr @scharrier I have updated the microcks pull request as it had a few unrelated changes, so you can clearly see what needs to be done in order for a OpenAPI to work with both Bump.sh and Microcks.

Microcks currently requires a) named examples, and b) variables in the response examples in order to reuse request parameters.

The names examples show up the same as usual, but they do make the OpenAPI a little more clunky.
The variables in the response show up literally in Bump.sh and this of course makes no sense to the user. So, questions:

Are we ok with the Train Travel API using this slightly more clunky OpenAPI for named examples? If not... I had mentioned to Microcks about supporting single example instead of only working with named pairs, but named pairs can be very powerful if used correctly. If we need Microcks to roll out a new feature before pushing collaboration this could be a blocker.

Are we ok with the Train Travel API demo showing these variables in there, or should we try and avoid that somehow.

A. Bump.sh Docs adds functionality to reuse values from the request to populate those variables and make for a heck of a powerful feature nobody else currently has.

B. We use overlays to add these examples and have a second Microcks-enabled OpenAPI document that is hosted elsewhere, which we then make available for the microcks team to pull in.

Probably B, I thought of that mid writing this all out. 😆

Still, thoughts on this would be welcome when you have a moment.

scharrier · 2024-11-20T09:44:52Z

100% agree with the overlays proposal: it will allow us to add advanced examples for mocking purpose without havint to complexify the original definition 👍

This will help make sure the OpenAPI is working well within Microcks.

lbroudoux · 2024-11-21T15:12:15Z

100% agree with the overlays proposal: it will allow us to add advanced examples for mocking purpose without havint to complexify the original definition 👍

We recently put together a new APIExamples yaml or JSON format, which we described here: https://microcks.io/documentation/references/examples/. There's also a companion JSON Schema you can use in your IDE to get completion while editing. From the first feedback we got, people tend to like it very much.

Let us know if we can help with anything in order to get this added to https://try.microcks.io

…yaml

philsturgeon · 2024-11-21T21:55:15Z

Right! @lbroudoux I have made a .microcks/ directory which has a overlays.yaml that contains all the microcks specific examples, and a ~~openapi.mock.yaml~~ openapi.yaml which is the generated result. Can you give it a spin and tell me if this looks ok, and if so I'll merge it. Then hopefully you can get it going on try.mockrocks.io as a running demo.

lbroudoux · 2024-11-22T09:52:44Z

Hi @philsturgeon

I'm sorry, but I think my previous comment about overlay was ambiguous. Actually, we don't support an OpenAPI overlay spec that uses patch-like commands.

What we do support is importing OpenAPI spec that just contains examples as secondary artifacts. You can see such an example here: https://github.com/microcks/microcks-quickstarters/blob/main/oidc/github.com/github-oidc-1.1.4-openapi-metadata.yaml

If you don't want to put all the examples in the original OpenAPI spec, you have the choice between:

Keeping an OpenAPI structure and just putting the example fragments in a secondary file - IMHO, the drawback is that fragments of the same examples are still split in different locations,
Use an APIExamples file that allows consistent declaration of request/response pair examples per operation - as introduced here https://microcks.io/documentation/references/examples/

Here's the result of using such a file for the Train Travel API:

apiVersion: mocks.microcks.io/v1alpha1
kind: APIExamples
metadata:
  name: Train Travel API - Microcks
  version: '1.0.0'
operations:
  'GET /stations':
    stations:
      request:
      response:
        status: '200'
        mediaType: application/json
        body:
          data:
            - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
              name: Berlin Hauptbahnhof
              address: Invalidenstraße 10557 Berlin, Germany
              country_code: DE
              timezone: Europe/Berlin
            - id: b2e783e1-c824-4d63-b37a-d8d698862f1d
              name: Paris Gare du Nord
              address: 18 Rue de Dunkerque 75010 Paris, France
              country_code: FR
              timezone: Europe/Paris
          links:
            self: https://api.example.com/stations&page=2
            next: https://api.example.com/stations?page=3
            prev: https://api.example.com/stations?page=1

  'GET /trips':
    trips:
      request:
        parameters:
          date: '2024-02-01T09:00:00Z'
          origin: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          destination: b2e783e1-c824-4d63-b37a-d8d698862f1d
      response:
        status: '200'
        mediaType: application/json
        body:
          data:
            - id: ea399ba1-6d95-433f-92d1-83f67b775594
              origin: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
              destination: b2e783e1-c824-4d63-b37a-d8d698862f1d
              departure_time: '2024-02-01T10:00:00Z'
              arrival_time: '2024-02-01T16:00:00Z'
              price: 50
              operator: Deutsche Bahn
              bicycles_allowed: true
              dogs_allowed: true
            - id: 4d67459c-af07-40bb-bb12-178dbb88e09f
              origin: b2e783e1-c824-4d63-b37a-d8d698862f1d
              destination: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
              departure_time: '2024-02-01T12:00:00Z'
              arrival_time: '2024-02-01T18:00:00Z'
              price: 50
              operator: SNCF
              bicycles_allowed: true
              dogs_allowed: true
          links:
            self: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01
            next: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01&page=2
  
  'GET /bookings':
    bookings:
      request:
      response:
        status: '201'
        mediaType: application/json
        body: 
          data:
            - id: bfc5af2c-f477-43c4-8bdf-a00bdb939d65
              trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
              passenger_name: John Doe
              has_bicycle: true
              has_dog: true
            - id: 1725ff48-ab45-4bb5-9d02-88745177dedb
              trip_id: b2e783e1-c824-4d63-b37a-d8d698862f1d
              passenger_name: Jane Smith
              has_bicycle: false
              has_dog: false
          links:
            self: https://api.example.com/bookings
            next: https://api.example.com/bookings?page=2

  'POST /bookings':
    new_booking:
      request:
        headers:
          Content-Type: application/json
        body:
          trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          passenger_name: John Doe
          has_bicycle: true
          has_dog: true
      response:
        status: '201'
        mediaType: application/json
        body: |-
          {
            "id": "{{ uuid() > put(bookingId) }}",
            "trip_id": "{{ request.body/trip_id }}",
            "passenger_name": "{{ request.body/passenger_name }}",
            "has_bicycle": {{ request.body/has_bicycle }},
            "has_dog": {{ request.body/has_dog }},
            "links": {
              "self": "https://api.example.com/bookings/{{ bookingId }}"
            }
          }

  'GET /bookings/{bookingId}':
    booking_1725ff48-ab45-4bb5-9d02-88745177dedb:
      request:
        paramaters:
          bookingId: 1725ff48-ab45-4bb5-9d02-88745177dedb
      response:
        status: '200'
        mediaType: application/json
        body:
          id: 1725ff48-ab45-4bb5-9d02-88745177dedb
          trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          passenger_name: John Doe
          has_bicycle: true
          has_dog: true
          links:
            self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb
    booking_bfc5af2c-f477-43c4-8bdf-a00bdb939d65:
      request:
        paramaters:
          bookingId: bfc5af2c-f477-43c4-8bdf-a00bdb939d65
      response:
        status: '200'
        mediaType: application/json
        body:
          id: bfc5af2c-f477-43c4-8bdf-a00bdb939d65
          trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
          passenger_name: Billy Bikeless
          has_bicycle: false
          has_dog: true
          links:
            self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb

What do you think?

philsturgeon · 2024-11-22T17:54:12Z

@lbroudoux hey you were clear, this overlay approach is something I thought up with the Bump.sh team. It's not something I expected Microcks to support, it's just a means of getting the original examples out, and the new examples in, and making a new openapi.yaml in .microcks/ thats specific to Microcks.

For example, I have updated microcks/community-mocks#25 to use the new URL that I would expect to work once this is merged.

lbroudoux · 2024-11-23T16:01:32Z

Hey @philsturgeon, @ChristopheDujarric, @scharrier and Bump.sh team!

The Train API is now available on https://hub.microcks.io! You can check it out directly here: https://hub.microcks.io/package/bump.sh

The Mocks have also been loaded on the https://try.microcks.io instance. You can directly check them there or try a simple call:

curl -X GET 'https://try.microcks.io/rest/Train+Travel+API/1.0.0/bookings' -H 'Accept: application/json'

Now let's see how we can showcase and promote this during APIdays Paris 😉

Cheers!

philsturgeon · 2024-11-24T15:22:05Z

@lbroudoux amazing, thank you so much for getting that done quickly (and on a weekend!)

I've just made #36 to help people see the mock server. Have you set this up to "pull" from the URL?

Becasue if so, you could chuck that config onto the draft blog post we've been working on, to show how it would work. Then we can just post about making changes to OpenAPI, pushing to Bump, and having it pull to Microcks.

lbroudoux · 2024-11-24T17:22:33Z

Hey @philsturgeon, thanks for the follow-up (still on the weekend 😉 )

If you connect on https://try.microcks.io using guest/guest, you can see in the Importers section that I created an importer to the GitHub repo holding the Train Travel OpenAPI. So: yes, updates will be pulled automatically by Microcks when you'll make some changes to OpenAPI and push them to Git.

I let the default scheduling configuration on "Try" instance so Microcks checks for changes every 2 hours.

.microcks/overlays.yaml

paulRbr · 2024-11-25T07:43:40Z

.microcks/overlays.yaml

+          value:
+            data:
+              - id: bfc5af2c-f477-43c4-8bdf-a00bdb939d65
+                trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e


Should this contain a “real” trip id? e.g. the ea399ba1-6d95-433f-92d1-83f67b775594 one?

paulRbr · 2024-11-25T07:44:13Z

.microcks/overlays.yaml

+                has_bicycle: true
+                has_dog: true
+              - id: 1725ff48-ab45-4bb5-9d02-88745177dedb
+                trip_id: b2e783e1-c824-4d63-b37a-d8d698862f1d


same here, guess it should be a trip id, e.g. 4d67459c-af07-40bb-bb12-178dbb88e09f?

paulRbr · 2024-11-25T07:45:25Z

.microcks/overlays.yaml

+          summary: John Doe
+          value:
+            id: 1725ff48-ab45-4bb5-9d02-88745177dedb
+            trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e


same here, let's use a trip id ea399ba1-6d95-433f-92d1-83f67b775594?

paulRbr · 2024-11-25T07:45:42Z

.microcks/overlays.yaml

+          summary: Billy Bikeless
+          value:
+            id: bfc5af2c-f477-43c4-8bdf-a00bdb939d65
+            trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e


and last a trip id from the examples data ea399ba1-6d95-433f-92d1-83f67b775594?

paulRbr · 2024-11-25T07:47:37Z

.microcks/overlays.yaml

+            id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+            trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e


again some two ids should probably be changed with the example booking id and eg trip id?

paulRbr · 2024-11-25T07:49:01Z

.microcks/overlays.yaml

+  - target: $.paths["/bookings/{bookingId}/payment"].parameters[?(@.name=="bookingId")]
+    update:
+      examples:
+        Card:


let's change the example names for a booking?

philsturgeon force-pushed the feat/microcks branch from 1f58daa to 0e9c6d6 Compare June 26, 2024 12:05

philsturgeon changed the title ~~getting examples working with microcks~~ Demonstrate Microcks Mocking Jul 25, 2024

philsturgeon force-pushed the feat/microcks branch from 475e00d to 777b99e Compare November 5, 2024 13:36

philsturgeon mentioned this pull request Nov 5, 2024

feat: consistent shared pagination params #32

Merged

philsturgeon force-pushed the feat/microcks branch from eee3c70 to 63166cb Compare November 5, 2024 13:53

philsturgeon commented Nov 5, 2024

View reviewed changes

openapi.yaml Outdated Show resolved Hide resolved

philsturgeon mentioned this pull request Nov 5, 2024

adding bump.sh's train travel api microcks/community-mocks#25

Merged

philsturgeon force-pushed the feat/microcks branch from 75e6f4e to cb423ca Compare November 21, 2024 13:00

philsturgeon added 9 commits November 21, 2024 13:02

getting examples working with microcks

5ce13ac

chore: add microcks spectral rulset

5ae670f

This will help make sure the OpenAPI is working well within Microcks.

feat: mark production as not internal

74a18cf

feat: name more examples in pairs for microcks

2836d9e

added mock server to servers

45d3e65

remove caching stuff for now

c81ed10

Silence failing rules for microcks

3030f1a

bring back seat preferences later

67526de

allow microcks back in for linting

4265225

philsturgeon force-pushed the feat/microcks branch from cb423ca to 4265225 Compare November 21, 2024 13:03

revert main openapi.yaml and make a overlay / generated openapi.mock.…

765262b

…yaml

philsturgeon force-pushed the feat/microcks branch from 7e72d8e to 765262b Compare November 21, 2024 21:52

add a script to remind me how to do this

25e1c78

disable linting on microcks openapi.yaml as it uses string examples

795048a

philsturgeon force-pushed the feat/microcks branch from 894c595 to 795048a Compare November 22, 2024 18:11

Regex...

ea7e90b

philsturgeon merged commit 4684b39 into main Nov 22, 2024
3 checks passed

philsturgeon deleted the feat/microcks branch November 22, 2024 18:22

philsturgeon mentioned this pull request Nov 24, 2024

feat: point to microcks mock server #36

Merged

paulRbr reviewed Nov 25, 2024

View reviewed changes

.microcks/overlays.yaml Show resolved Hide resolved

paulRbr reviewed Nov 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Demonstrate Microcks Mocking #21

Demonstrate Microcks Mocking #21

philsturgeon commented Jun 26, 2024 •

edited

Loading

philsturgeon commented Nov 5, 2024 •

edited

Loading

lbroudoux commented Nov 5, 2024

grossyoan commented Nov 18, 2024 •

edited

Loading

scharrier commented Nov 20, 2024

lbroudoux commented Nov 21, 2024 •

edited

Loading

philsturgeon commented Nov 21, 2024 •

edited

Loading

lbroudoux commented Nov 22, 2024 •

edited

Loading

philsturgeon commented Nov 22, 2024

lbroudoux commented Nov 23, 2024

philsturgeon commented Nov 24, 2024

lbroudoux commented Nov 24, 2024

paulRbr Nov 25, 2024

paulRbr Nov 25, 2024

paulRbr Nov 25, 2024

paulRbr Nov 25, 2024

paulRbr Nov 25, 2024

paulRbr Nov 25, 2024

		id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
		trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e

Demonstrate Microcks Mocking #21

Demonstrate Microcks Mocking #21

Conversation

philsturgeon commented Jun 26, 2024 • edited Loading

philsturgeon commented Nov 5, 2024 • edited Loading

lbroudoux commented Nov 5, 2024

grossyoan commented Nov 18, 2024 • edited Loading

scharrier commented Nov 20, 2024

lbroudoux commented Nov 21, 2024 • edited Loading

philsturgeon commented Nov 21, 2024 • edited Loading

lbroudoux commented Nov 22, 2024 • edited Loading

philsturgeon commented Nov 22, 2024

lbroudoux commented Nov 23, 2024

philsturgeon commented Nov 24, 2024

lbroudoux commented Nov 24, 2024

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

paulRbr Nov 25, 2024

Choose a reason for hiding this comment

philsturgeon commented Jun 26, 2024 •

edited

Loading

philsturgeon commented Nov 5, 2024 •

edited

Loading

grossyoan commented Nov 18, 2024 •

edited

Loading

lbroudoux commented Nov 21, 2024 •

edited

Loading

philsturgeon commented Nov 21, 2024 •

edited

Loading

lbroudoux commented Nov 22, 2024 •

edited

Loading