bump-sh-examples
Demonstrate Microcks Mocking
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.
@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
exampleinstead 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.
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.
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
exampleinstead 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.
100% agree with the overlays proposal: it will allow us to add advanced examples for mocking purpose without havint to complexify the original definition 👍
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
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.
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
APIExamplesfile 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?
@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 https://github.com/microcks/community-mocks/pull/25 to use the new URL that I would expect to work once this is merged.
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!
@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.
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.