Add API endpoint to read list of guides for a stack

[durden]

We've received interested from the community in featuring guides on their sites. This is especially useful for the tutorial contest. Sponsoring companies would like to be able to automatically pull published guides related to their tools and promote links to the guides on their site. This would be great for guide authors because it gives their content more exposure.

The best way to do this would be to provide a simple API endpoint to get a list of guides related to a particular stack.

[durden]

The endpoint could live at a URL like, /api/list-guides/ and require one extra argument for the stack. The return would be a JSON data structure with a list of guide 'objects'. Each guide 'object' should have at least the following information:

• Title
• Author username
• Full URL to hack.guides() website
• Number of hearts
• Short summary of guide

[durden]

We currently have all almost all of this information in the redis hearts database and the details.json file in the github repository. The only thing we're lacking is a guide summary.

We could make the summary very simple and just use the first x number of characters in the guide. This simple solution presents a few problems:

1. The guide content is raw markdown so we'd need to return rendered html for the summary.
2. The first couple characters of a guide may not provide an accurate summary of the guide.

So, we may want to implement #20 and use the commit message to hold the summary. Then, we could retrieve the summary of a guide by reading the commit message of the first commit to a guide. The commit sha of a guide is typically stored in the first_commit attribute on the models.article.Article object.

[durden]

Something else we probably want to provide in the API is the ability to search on tags. This way API users could further filter their guide searches.

The ability to tag a guide is not added yet, but it's being discussed in #97.

[durden]

Any additional thoughts on adding or not adding an API @paulocheque @edroman @prtkgpt ?

[durden]

One last thing. This feature will be especially useful for the tutorial contest so if we implement it doing so in the next 3 - 4 weeks would be preferable.

[paulocheque]

During the editor submission, we can collect the first rendered paragraph and consider it as the article summary. Limiting to X chars to avoid big summaries.

I would use GET /api/guides or GET /api/articles instead.

[durden]

That all makes sense and is easy to implement. However, capturing the first X characters of rendered HTML is tricky because we need to close tags, etc.

Also, that doesn't address the problem of the first X character not providing a good summary of the guide.

Finally, HTML is verbose so if we got that route we might need quite a few characters in order to grab something useful.

On Thursday, June 16, 2016, Paulo Cheque notifications@github.com wrote:

During the editor submission, we can collect the first rendered paragraph and consider it as the article summary. Limiting to X chars to avoid big summaries.

I would use GET /api/guides or GET /api/articles instead.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/pluralsight/guides-cms/issues/96#issuecomment-226523255, or mute the thread https://github.com/notifications/unsubscribe/AADiz5halRxlCziFOQW9X7GGAYIWhIgUks5qMW0ngaJpZM4I3J-L .

[paulocheque]

We can use jQuery to collect this text, something like $('p:first').text(). But yes, if the first paragraph is not relevant, then it would be useless. Unless we recommend as a good pattern to always start your guide with a brief introduction.