Questions for folks who work a lot with front end js that calls back end methods to get and save data: • How do you document your APIs, to coordinate between front- and back-end devs? • How do front-end devs work on their rendering before the back end is ready to call? ◦ For instance, do back end devs create stubs that return hard coded mock data first, before writing real code? • How do back-end devs test before the front end exists to call it and display results? ◦ I assume the answer here is usually writing tests for TestBox, yes? In the past, at other companies, we built a bunch of in-house infrastructure around this stuff. My current company is moving towards this style of development, so we're thinking about these sorts of tooling. Any thoughts on specific tools and best practices would be much appreciated.

front end devs can mock the end points their going to call, back end and front end can be worked on in paraell

How do they know what to mock? I'd think the APIs would need to be documented first. How do you do that?

This is not with my "CFML" hat on, but our current stack has a NestJS backend, and (several) VueJS frontends, with a 3rd repo which has a shared framework between the two (which is installed as a package). Our model definitions get created in the API, then written to the framework in JSON, so the front end and back end can both use the same models & types. This is all autogenerated from the swagger/OpenAPI definitions, so we can also generate the API docs from the same source. As it's in all in Typescript, when you're building out the front end, you can just import the models from the framework, and you get all the type checking and autocomplete goodness. We've got to the point where if we write code to hit an endpoint from the front end with incomplete data (or the wrong type), it'll flag it in VSCode immediately etc. As we've got a central source of truth for the models, we can easily use faker.js for mocking data. I guess being a full JS stack, we tend to have the same person working on the front and back end implementation...

on the occasions we have front end people working on stuff, they hit our API docs produced by cbswagger which our back end devs write in YAML

We have a JS frontend and a non-JS backend so I'll tell you what we do: • Document the APIs in a tech-neutral language (that said, we show JSON for both inputs and outputs) • We originally wrote those docs as a spec for both the frontend and backend folks to write tests and code against -- and initially had them on an internal server; now they're part of our API project and the API itself can render those docs on a specific URL (

/docs/

) -- more below • The frontend folks will use mocks for API calls, and will generate test data based on what the API docs say the APIs accept and return • The backend folks will write tests (first!) against those API docs, using HTTP calls in the tests -- we write tests for all the error conditions outlined in the API docs first and get those to pass (parameter validation etc), then we start writing tests for the various "happy path" combinations and then get those to pass • We push an initial version of the new APIs to the repo, the CI system runs all the tests and if they pass, a new build is deployed to the staging system • At this point, the frontend folks can also test directly against the staging backend (they have both mock tests and some real tests) Docs as part of the API: We write our docs in Markdown and generate the completed docs using Daux which is a PHP application. That generated HTML is not checked into version control (the source

.md

files are). The Daux process can be run locally (via

docker run

) if necessary to preview the docs but it is normally run as part of the CI process so that a snapshot of the docs are captured in the package that is deployed to staging (and then later deployed to production), so that the API always serves up the matching version of the docs -- and staging API may be ahead of production API so this keeps the docs in sync. If you're curious: https://api.worldsingles.com/docs/

Great stuff folks, keep it coming. I'm not seeing CF's API tools mentioned here, probably because your API initiatives predate them. Has anyone investigated them, or even better, used them?

probably because your API initiatives predate them

Well, we switched from ACF to Railo around CF9 (it was in prerelease at the time) but I wouldn't have used Adobe's API Manager even if we'd stayed with the commercial version -- I just don't want to be locked into a single vendor for that sort of stuff... And Adobe's REST and GraphQL stuff is... not something I'd want to use either...

Related, not to derail my own thread, but talk to me about why REST APIs vs not.

Depends on what 'not' means

Even back when we used ACF (we had CF8 Enterprise in production when I joined, back in 2009), we steered clear of the vendor-specific stuff -- because Macr/Adbe have a habit of tying that stuff into weird libraries etc and then not updating them, so you run into bugs and security issues and you can't update them yourself, and then they deprecate stuff and you can get screwed that way. With the rewrite my team started (replacing the old everything-in-

.cfm

code with modern ColdBox / CFC based code), we deliberately wrote portable code so it would run on both CF9 (prerelease) and Railo... I've always been a fan of portable code (from writing / contributing to OSS stuff, including FW/1).

^^^^ this is a good policy regardless of your preferred engine, Lucee has their own REST stuff which we also never use for the same reason. CF rest template (and taffy, afaik) are 'just CF'

And if it was ever needed, Taffy is open-source - so even if it was abandoned - you can still make any needed changes and keep using that library.

Hi @Dave Merrill, your question itself raises questions that draw my attention and interest. 1. When you say, "How do you document your APIs", who does "you" refer to? A Front-Ender? A Back-Ender? A Third-Party API Provider? Some other party? I think the stance of the documenter is crucial. 2. Client-Server design says that, ideally, front-end and back-end should be as decoupled from each other as possible. (For the sake of maintainability, scalability, and so forth.) Why then would you want an API provider "to coordinate between front- and back-end devs"? 3. "How do front-end devs work on their rendering before the back end is ready to call?" . Shouldn't they be independent of the back-end and mock up a back-end of their own? 4. "How do back-end devs test before the front end exists to call it and display results?" Shouldn't they be independent of the front-end and mock up a front-end of their own? I can assure you I'm not being funny. That is just how your description excites my interest.

@bkbk 1. We're a relatively small dev team, 2 + 1/4 (manager/developer) full stack people, hiring a new front end person shortly. There's nobody else to design or dictate the components, methods, arguments, data formats or any other expectations, it's up to us. That said, I don't expect a front end person to be in a good position to architect most of this, since they're not involved in the design of the db schema, or most likely, the actual application requirements. So, API design probably ends up with the back end folks, with some kibitzing/dictation by that manager/developer. I do expect font end folks to speak up when data they need is missing, or in an awkward format. 2. Client/server separation doesn't mean that front and back ends don't coordinate. How could that work? Front end needs to know what methods exist in the back end, their arguments, data formats, requirements and expectations, and how error conditions will be communicated back to them. (Like missing or invalid arguments, business rule violations, actual errors.) I must be missing something about an alternative you're suggesting. 3. Maybe the front-end people mock up the data they expect to receive, or maybe the back up people mock up the data they expect to return, or maybe some tooling generates mock data from the specs defining the methods and their return data. I'm interested in hearing about how all of this happens in other organizations 4. As I said, I expect the back end to be tested procedurally via TestBox or an equivalent, without the need for the actual front end. Make sense?

It makes sense. Given a business problem, the way we do it is to begin with a minimal, well-documented API design. We talk about requests and responses, but there is no talk yet about front-end and back-end. Pretty much as Sean describes it in the bullet-points.