search

apiaryio / api-elements

API Elements is a structure for describing APIs and the complex data structures used within them.
http://apielements.org/
MIT License
28 stars 10 forks source link

Extending API Elements #12

Closed smizell closed 8 years ago

smizell commented 8 years ago

Provides instructions for extending the API Elements and an element for adding in user-specific data.

pksunkara commented 8 years ago

@smizell Why is this not an RFC and made a PR on refract project repositories?

smizell commented 8 years ago

@danielgtaylor I've addressed your comments.

@pksunkara as API Elements has moved to it's own repo in Apiary and has separated from Refract, we'll need to start working on changes here I believe. I think we should probably remove the API Elements files from the Refract repo as well and use this as the definitive definition of the resource.

However, I'm really open to ideas as I'm just trying to get this change through. How would you foresee this working best now that it is a separate project?

pksunkara commented 8 years ago

API Elements has moved to it's own repo in Apiary and has separated from Refract

That has been a surprise for me recently. I guess I am just confused about how the whole thing works. Will we remove API Description namespace from refract project and just leave the base refract there?

Even if API elements has moved here, don't you think we should have a RFC process?

pksunkara commented 8 years ago

And why is this named api-elements instead of api-description since the name is API Description Namespace. Or did that change too?

smizell commented 8 years ago

@pksunkara this is for branding purposes. API Elements is kind of a formal title for the project, which is simply for the API description namespace. Similar to how our markdown format is called API Blueprint.

Looks like you merged it. Do you think this is a good/wise change to make?

smizell commented 8 years ago

That has been a surprise for me recently. I guess I am just confused about how the whole thing works. Will we remove API Description namespace from refract project and just leave the base refract there?

We should consider this, I'd say. This is similar to how you'd consider the relationship of RSS to XML. RSS uses XML, but XML is the format that RSS uses for its basis. RSS then becomes kind of the brand name of the format that people talk about instead of saying the "News Namespace" for XML.

Even if API elements has moved here, don't you think we should have a RFC process?

I'm open to that, though I think others were thinking for now we could use PRs as a primitive RFC.

pksunkara commented 8 years ago

@smizell Then let's remove the API Description Namespace from refractproject.

API Blueprint and MSON already has RFC process. So, I think this should too.

smizell commented 8 years ago

Then let's remove the API Description Namespace from refractproject.

I think we should first change those files to say, "This spec has moved to API Elements," since I think we use those links somewhere.

API Blueprint and MSON already has RFC process. So, I think this should too.

Sounds good to me :)

danielgtaylor commented 8 years ago

API Elements is kind of a formal title for the project, which is simply for the API description namespace.

Let's not forget that it also includes the parse result namespace ;-) I'd say API Elements is kind of a formal title and set of concise and complete documentation that encompasses parse result, API description, and data structures from Refract for the purpose of marketing/education and reference.