Spec version vs. Implementation version


#1

One of the benefits of RAML is to iteratively transition from a spec to an implementation (with overlap) while durably carrying over the documentation and samples. How do you see getting early feedback from your consumer developers? A/B testing applicable here?


#2

So far the only main example seems to be the client in the API Notebook


#3

First step is to really ease that design process itself, so the new mocking service coming online very soon will help.

But then the consumer feedback would probably be done the way all such feedback happens: exposing the full gamut of consumption experiences and getting feedback. So…

  1. The API Console gives you documentation and can be used to hit the API and run it through its paces
  2. They can use curl or Chrome postman or any other tools you use today to hit the API
  3. As pspeter3 mentions, they can script against the API (e.g. the mocked endpoint) using the API Notebook

A/B testing can certainly be very useful here. And to that extent, versioning is a very interesting question: we usually regard version as sequential, progressing from one version to the next incremental one, and publishing every so often. But for A/B testing you want parallel versions, and then convergence after a decision is made. Are there some established conventions for versioning in parallel tracks, essentially branches?


#4

We just started using RAML and like it very much. We are very interested in the new mocking service. Any ideas on the rough timeframe it will be available?

I also have a question on the generated documentation and the best approach to making it available online for consumption. I have installed the API console locally and can get it to generate the documentation, which is great. But, I want to make the documentation available online permanently for our team without having to go through the console. What is the best approach to doing this?


#5

So, I believe I have figured out my second question. If there is a better way, please let me know, but I’ll include what I did here to help others that are starting out.

The README.md file contains instructions on how to do this, but the file to modify was not immediately obvious to me (this is my first experience with actually using node as well).

After you have the console running, you need to locate the index.html file in the app directory (should be api-console/app/index.html). Within this file, find a line similar to:

<raml-console with-root-documentation></raml-console>

Simply change it to include the RAML you want to make available and save it and it will show up automatically. For example, you can include one of the examples that comes with the project, such as:

<raml-console with-root-documentation src="examples/simple.raml"></raml-console>

In addition, you can have only the documentation appear (and not the console), by either commenting out or removing the <raml-console-initializer id="raml-console-loader"> block of code.

Hopefully this will help someone else starting out and if there is a better way to do this, please let me know.


#6

Hi David,

We’ve got the mocking service under active development, with a few open questions that we’re working diligently to resolve right now. We expect this to come out in a public Beta quite soon, and I’ll get you a hard date as soon as I have one.

Thanks,
Dillon


#7

That’s great to hear. Thanks for the quick reply.


#8

Hi.

Sorry to be a nag but do you have any idea yet regarding the date your mock server will be available?
Is it still pegged for an imminent arrival?
I’ve been looking around and I quite like http://wiremock.org for this purpose, it will take some coding to get it to work seamlessly with raml files though.


#9

Very imminent. We’re dev complete and doing QA at the moment, and will have something released ASAP.


#10

Update: it’s finishing QA now, which took longer than anticipated due to some logistics conflicts, so we’re anticipating a (beta) release to production early this week.


#11

Good to know, I am childishly exited about this :slight_smile:


#12

End of this week (high confidence). Sorry for the delay - logistics!


#13

Hi guys,

“formal” announcement coming soon, but wanted to drop you a note and let you know we’ve just released the RAML mocking service. It’s integrated with the API Designer, and can be checked out over at http://api-portal.anypoint.mulesoft.com/raml/api-designer

//Dillon


#14

Nice!
Thanks so much, going to check it out now.


#15

Updated link: sign up at https://anypoint.mulesoft.com/apiplatform/ and create an API, then create or edit its RAML spec in the API Designer, and turn on the mocking service to bring it to life. The mocking service follows every change you make in the RAML and adjusts itself to reflect the latest valid RAML, continuously.