https://linen.dev logo
Join Slack
Powered by
Does anyone have the answer to this question? <htt...
# random
m
Does anyone have the answer to this question? https://twitter.com/rdrn_/status/1597281661854846976
Seems very thin on the ground in terms of the ability to maintain a reasonable documentation of 3rd party APIs Most companies pull data from 20+ sources. Fivetran API spec is a Google Slide… 😭
e
I wonder if something like schemastore exists for API docs. Something like that would definitely be useful to generate clients, build Singer taps, and more 😄. I might give that a try in my free time.
j
we also use postman to document partner APIs
m
@jacob_matson can you please share how you do this?
j
if possible, we import the docs from swagger etc to postman. Otherwise we add them by hand. basically so that the initial profiling of API responses can be done by my team (ops) and it gets to dev with a decent understand of how these things actually work. More here https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-postman-data
a
@jacob_matson - Does Postman give any way to publish publicly the imported/profiled API definition? Riffing on @edgar_ramirez_mondragon's idea, I wonder if we could literally send other API's JSON Schema to schemastore.org. So, if Slack (for instance) doesn't publish a machine readable JSON Schema or slack for their API endpoints, we could detect one and publish to schemastore.org. Then, the vendor and/or the community could manage there. The ownership model is janky, but hard to argue its not better than nothing. 🤷
Taking for example, the 
milestones
API endpoint for GitHub - could have a lifecycle maintained externally instead of being maintained in the tap here.
j
Does Postman give any way to publish publicly the imported/profiled API definition?
yes! we use it occasionally when giving access to our customers although usually they just say “send the swagger docs”
a
> Does Postman give any way to publish publicly the imported/profiled API definition?
yes! we use it occasionally when giving access to our customers
@jacob_matson - Do you mean self-hosted or a shared hub? Can you point me to an example or a docs entry? From the importing/exporting link above I don't see any options for serving or publishing the definition.
j
a
Got it - Thanks!
@matt_arderne - Back to your original inquiry. I was able to very quickly import the URL for the published OpenAPI spec for shortcut.com into a web-based Postman workspace here. Does it seem like this is a step in the right direction to your inquiry? Presumably the adapted method would be to describe the 'not my API' from scratch and then publish the created definition.
message has been deleted
Consumers apparently have the option to 'fork' your definition if they want/need to make changes/fixes.
(FWIW, on principal I don't have a paid account. Looks like most of these features are free in terms of ability to publish/fork/consume definition.)
m
@aaronsteers that is super interesting, and I think a lot more than I was expecting. Let me have a closer look!
Sharing for what it may be worth to someone, I came across a few other tools in the scratch patch • Metlo - can scan existing APIs (more SecOps) • Wundergraph - GraphQL tool, quite cool, you respecify all external 3rd party APIs as GraphQL “internal” APIs • Not sure about this one: https://the-guild.dev/graphql/mesh
@aaronsteers I think this tool is probably a better direction in terms of what I’m trying to achieve https://github.com/lithictech/moxpopuli#:~:text=Mox%20Populi%20is,and%20API%20governance. (Postman feels like it prepopulates a postman collection for dev work, where as I think my primary use case is to form the basis for API documentation, of all resources, and then build into monitoring services etc)
Chatting to the developer on Twitter he gave this disclaimer around when to use this https://twitter.com/robgalanakis/status/1597637662621696000
j
this tracks w/my experience
Open in Slack
PreviousNext
Powered by