search

programminghistorian / ph-submissions

The repository and website hosting the peer review process for new Programming Historian lessons
http://programminghistorian.github.io/ph-submissions
137 stars 111 forks source link

Review Ticket for Creating APIs with Python and Flask #106

Closed walshbr closed 6 years ago

walshbr commented 7 years ago

The Programming Historian has received the following tutorial on 'Creating APIs with Python and Flask' by @smythp. This lesson is now under review and can be read at:

http://programminghistorian.github.io/ph-submissions/lessons/creating-apis-with-python-and-flask

Please feel free to use the line numbers provided on the preview if that helps with anchoring your comments, although you can structure your review as you see fit.

I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to @ianmilligan1 or @amandavisconti if you feel there's a need for an ombudsperson to step in.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. If anyone witnesses or feels they have been the victim of the above described activity, please contact our ombudspeople (Ian Milligan and Amanda Visconti - http://programminghistorian.org/project-team). Thank you for helping us to create a safe space.

walshbr commented 7 years ago

I'll take a look at this in the next week and reach out to reviewers. Looking forward!

walshbr commented 7 years ago

Thanks for this, @smythp! I think this is useful in a lot of ways. In particular, your thoughts about API design are compelling, as are your explanations of the concepts that lie underneath it all.

My main thoughts have to do with reorganizing things slightly and more clearly crafting the API so that it serves a particular case study. In particular, I would try to break apart some of the longer code blocks so that they build up piece by piece rather than dropping a large chunk of code on the reader at once. And then I would rework the API just slightly so that it's one consistent use case throughout. In this case, it seems like you're building to a book catalog. I'd start with that even when just stubbing out the basics of an API. And then I think it could help to tie the API back to the sorts of use cases you imagine for such an API. What might a digital historian want to explore? How can this API help them? What questions can you answer with your requests? I think situating the lesson in a consistent case study like that will help to direct more towards the type of readers we imagine for the Programming Historian. And it will help ground people in the useful theoretical concepts you're discussing.

Given that I'm suggesting some fairly significant restructuring of (at least) the code here, I think it makes sense to wait on having reviewers check it out until after you've had a chance to account for my comments. Let me know what you think though. I can at least reach out to people to secure interested readers in the meantime, and I'm happy to discuss anything from below as you'd like.

My line by line notes follow:

Prerequisites - Will the lesson work across operating systems? You mention OSX and Windows, but what about installing Python etc. in both environments. I'd also mention what version of Python you are using and whether that matters. You could also point readers to other Programming Historian lessons where they could find information about how to install or work through particular elements. Just noticed that you mention the Python version lower in the lesson, but I think I'd include this info earlier.

What is an API?

Could be useful to give an example of an API, particularly one relevant to historical research if you've got one ready to go. That would help ground the theoretical discussion and help supplement the discussion of the Twitter API. Just a couple more sentences would be helpful here I think.

Using APIs

Could be useful to point people to another API if they're interested in learning more. And again, a couple examples of collecting data or taking advantage of a service could help ground the discussion in ways meaningful for digital researchers. Perhaps overlaps with the "data in real-time" point, but another reason for making an API might be if your data will be changing regularly and you want users to have access to those changes.

I wonder if it is worth adapting the Hello World example slightly. After all, they can get a version of that Flask app from other tutorials. Maybe adapt it to be thematically in line with the kind of API that they'll be producing? That way the beginning moments won't seem quite as much throwaways but will instead grow into the API example.

Installing Python and Flask I might put this section through paragraph 17 at the front of the lesson so as to collect setup and prereq's in one space early on.

Creating a basic flask application "Flask is a web framework for Python, meaning that It p" - capitalization of It here.

At paragraph 23 - I would give the terminal commands and output that create a folder structure as you specify.

Here - "The methods list lets Flask know" - I would reiterate which piece of the code is the methods list - methods=['GET'].

Might be worth reiterating at paragraph 41 why people shouldn't worry about not understanding those pieces here by reiterating what they should be understanding. I take the important point to understand here is more the general sense of how the API is fitting together.

To further assist in the theming of the API, I might add something to the 'hello world' index page of the API that describes the content/purpose of the API that you're constructing.

I might offer a note about "why Flask" for this sort of API work as opposed to any number of other options.

At paragraph 42, I think this might be a bit too big of a chunk of code to add all at once. The comments are helpful, but can you break this step up into two or three shorter steps and narrativize it a bit more to elaborate on what the comments are telling the reader?

At paragraph 49, I think you have a good opportunity to reiterate why someone might want to use an API like this. If the dummy data you're providing is meaningful, you could spin out a scenario like "A user coming to our site interested in looking for information about these books could do X, and then they could do Y with that information."

Design Principles This section is very good. I might elaborate a bit more on the counterexamples that you offer as a way of further explaining the distinctions between good and bad API's. You might even start with the bad API first and then work step by step towards the good one, explaining each improvement as you go rather than giving the good version all at once.

Also might be worth reiterating that when you talk about "designing requests" you are basically describing how you formulate the available and valid URL's that your app delivers (unless I'm mistaken). Short explanation like that might help connect the higher-level conversation to the nuts and bolts of assembling the API higher up. Might even be worth showing the explicit line of code where the request URL is formed and showing how you might alter it in the python file.

Documentation and examples

I think this section actually articulates what I think would really help the lesson - documenting the API that you're having people design. Give it a clear reason for being that aligns with a research problem, document it as a case study, and have that example API build throughout the lesson.

Paragraph 59 - again, I think the example here would be improved by building up a bit at a time and expanding the code commenting to help narrative the experience for the reader.

At the end of this section, once you've more consistently incorporated a particular example API, I think you could offer a couple research questions that someone might approach your API hoping to answer. They're implied by the requests, I think, but pulling them out and giving the context for them might help.

On that same note, I think the last paragraph of the lesson can be expanded slightly.

In the final example section - "To run the final example, first download the example database from this location and copy the file to your projects folder." I think you'll actually want them to download the database to the projects/api folder, since you have them working in the api folder, right? Otherwise the path to the database would be '../books.db'

smythp commented 7 years ago

Hi Brandon,

Excellent and clear suggestions, I'm looking forward to digging into this. A number of these I was also concerned about, but was afraid of making the article too long. I should be able to get a new version in the week after DH. Perhaps I'll see you in Montreal!

Best, Patrick

walshbr commented 7 years ago

Same! Would love to say hello if you find time.

smythp commented 7 years ago

I've pushed my updated version, rewritten to more clearly reflect humanities use cases. The main use case is a "distant reading archive," one that has metadata useful for distant reading, in this case first sentences. I've also included a shorter, more history-centric use case in the "Using APIs" section which gives a gentler introduction to a few API concepts than was present in the previous version. Many other edits. I've added a resources section to the end, but could be persuaded to expand or drop it entirely--let me know if you think it's actually useful for the target audience

Thanks, and looking forward to hearing what you think!

walshbr commented 7 years ago

Thanks, @smythp - I'll take a look at this later in the week!

smythp commented 7 years ago

Great! Looking forward to your feedback.

walshbr commented 7 years ago

@smythp - looks good! I think the added bits illustrating use cases are helpful, and they really help to ground the lesson in a particular audience. I've added notes below based on my most recent read. Nothing substantive at this stage from though - just typos and notes about one or two places that could use another sentence. I'll reach out to reviewers. Feel free to go ahead and make these changes if you think you'll have a minute in the next week. If not, you can just wait until after the other reviewers have taken a look. I'll reach out to people now.

paragraph 12 - I'd note that the Programming Historian's Python installation is for Python 2, not 3 as this lesson uses. paragraph 17 - "An alternative to FTP (file transfer protocol, or “regular” downloads) is the distributed torrent protocol, which can be viable for large files if users are willing to continue to “seed.” or upload portions of a file after downloading." Probably don't want the period after "seed"? maybe or upload in parentheses or set off with commas.

"Torrenting has its own disadvantages, such as that torrent traffic is blocked or monitored on many campus, library, and workplace networks." I might make "such as that" simple "as".

paragraph 20 -

Something wonky going on here with the markdown parsing for the second bullet point. Might be the parentheticals affecting the closing double asterisks?

paragraph 29 -

I might add the caveat that 12,243,633 is the number at the time of writing, as they could add more objects. And they have, in the time since you wrote that line and when I ran through it myself.

p 31 - Might be worth noting that it's in the documentation for an API where you'll find the query parameters.

p 32 - I'd mention that you're truncating the results and pulling out just one piece of them here.

p 38 - "meaning that It provides" capitalization of It

" Why Flask? Python has a number" - probably want those asterisks to be rendered as something right?

p 43 - the code block here has an extra quotation mark at the end of the return statement that causes it to error.

p 46 - I might more this note about learning command line earlier, maybe up by p 40.

p 55 - "(to send data)and" space

p 56 - "compoenents" spelling

p 64-66 - I would reference back to the work you've already done explaining how api's are structured. Or you could just further elaborate on how readers will learn more about that API further down.

p 65 - the link to the url here is incorrect - it's missing "/resources/books". Should be http://127.0.0.1:5000/api/v1/resources/books/all. ditto at p 71 i think?

p74 - "URLs like this (after the ?)are" space after the parentheses

p81 - "which corresspond to reading from a database." spelling on correspond

p84 - maybe a sentence on how spaces are handled in query parameters given "Le Guin"? I see that you discuss this later, so might be fine.

p79 - 88 is great

smythp commented 7 years ago

Didn't realize markdown inside HTML tags doesn't get rendered, ha. Will do a PR this weekend at the latest. Thanks, Brandon!

walshbr commented 7 years ago

I've found two reviewers for this @smythp - @mkudzia and @greebie (the latter reached out with interest when the first traces of this went up on the repository). I've let them both know that you'll be putting up a pull request with those very small changes in the next few days and that they shouldn't check it out until that time. Looking forward to working with you all!

smythp commented 7 years ago

OK, it's ready for review. I may do one last pass this evening, if I make changes I'll reference the commit here. Thanks again!

walshbr commented 6 years ago

Cool thanks! @mkudzia and @greebie - you should be good to go whenever you have time for reviewing. Let me know if you have any questions, and I'll check back in few weeks.

walshbr commented 6 years ago

Blargh - sorry. Ref'd wrong ticket in the above commit. That reference can be ignored.

greebie commented 6 years ago

Thanks for the interesting and informative tutorial!

Overall, I think it achieves its intended purpose, but could use some revisions along the following lines:

  1. The tutorial seems to extend beyond its focus, making it too long and as a result slightly intimidating. I think that the examples related to using an API and designing/documenting an API might be better as separate tutorials, leaving the focus for this tutorial to be setting up the API with Flask.

  2. I would re-target this to a beginner Python user or programmer. Targetting for someone completely new to coding seems to be taking the tutorial to places that seem unnecessary or off topic. It would be hard for the coding novice to get to flask anyway. You can also request that the user read some of the Python tutorials already available in PH.

  3. My interest in this tutorial is because I am interested in sharing data from Web Archives and promoting them for historical use. Also, having data in a standard format is good for comparative studies (cf the Policy Agendas Project http://www.comparativeagendas.net/). It may also be helpful for large scale collaborative historical research. You could either use historical examples or set up the Hugo example more to illustrate why a historian / humanist would want to build such an api.

  4. The example graph at the end might confuse the reader, as you do not explain how someone would create an online visualisation using your data. Pictures are almost always welcome, though.

  5. Some of the text can be reduced by providing succinct comments in the code, rather than describing it later. For example, someone who knows Python will understand imports, basic class instantiation and DEBUG configurations. You use code commenting well in some cases, but not in others.

A few paragraph-focussed comments:

1, 2, 3 > Consider converting these to point form, so the user can scan whether this tutorial is for them.

Installing Python and Flask

It may be the case that the user has Python 2.x, which can cause some grief on their part. I understand you probably do not want to get into venv here, but maybe you could link to some resources on how to manage dependencies via Python 2 & 3.

15: "Web APIs are often called HTTP or REST APIs" is technically untrue. There are a variety of web service apis that are not RESTful. Maybe reword to suggest that REST is the most common and easy to use web service api.

17: I am not sure this paragraph is needed. It would be better just to focus on learning the api, rather than torrents.

20: I feel the description of REST could be a bit more specific. Include short details that explain that REST uses the URI to access data.

21-33: I think the section on how to use an API takes the focus away from the lesson. Is there a tutorial somewhere on how to extract data from an API? I kind of feel like this must be covering old territory.

75: You refer to query parameters a second time here. I do not think you need to define it twice. Alternately, maybe you could include a glossary and link each time you use the word.

walshbr commented 6 years ago

Thanks, @greebie! @smythp - if you don't mind, let's wait for feedback from @mkudzia before you go implementing the changes she has suggested. Then I'll summarize the reviews and offer final suggestions for revision. But if you wanted to discuss anything further on the thread here feel free to do so.

smythp commented 6 years ago

Hi Ryan,

Thank you for reading the tutorial and for your thoughtful comments! I'll take Brandon's advice and wait for Megan's feedback before asking for clarification and implementing your suggestions. Thanks again, and looking forward to improving the tutorial using your comments.

Best, Patrick

mkudzia commented 6 years ago

Hi Patrick,

I will follow Ryan's format and give some overview comments up top, and then some line-based things I noticed. Overall it's clear you've done a lot of work on this and it shows! I agree that in general this is a really useful tutorial.

  1. I agree that it could be tightened up by splitting it into two or three smaller tutorials. I am a huge fan of good documentation so I'm really pleased that you put it in, but I also think ultimately there's enough here that it could be a tutorial in its own right. Maybe in this one you could sort of teach by example and keep the documentation examples/suggestions very tightly scoped on what you'd need for this specific API, then think about a separate API Best Practices tutorial in the future.
  2. I noticed a few places where there's some more advanced code-related language (specifically, the second sentence of "Lesson Goals," and line 63 jumped out at me) which would probably make neophyte programmers nervous. You could either double down on making this for beginners by clarifying or rearranging those sections (specific suggestions below). Alternatively, you could consider moving your suggestion that folks start with some of the other Python tutorials if they are new to Python. I would lean toward the latter but I think either could work.
  3. I thought your examples were extremely useful. I thought it was helpful for you to walk folks through using Chronicling America early on (lines 21-23), to get an obviously scholarly use case, and then moving on to something which could be scholarly but is also fun. As a point of interest, you don't say where you found the first sentences and book data. Did you compile by hand, or find them online somewhere? It would be useful for your users to know.
  4. In my opinion, you do a good job of walking people through the command line stuff. However, since I'm pretty comfortable there, it wouldn't hurt to see if you can bribe someone less familiar to check that for you.

Ok, moving on to the section- and line-based comments:

Lesson Goals:

Specific simplification comment for Python neopyhtes, as promised above:

greebie commented 6 years ago

Great commentary @mkudzia!

It's too bad we don't have anything available yet to explain how to use an api. It would be a popular tutorial I think.

That said, I am fine with any approach that improves the focus of the tutorial to accord with the lesson goals (including revising the lesson goals to include the above). I see my comments above more as an example where new ideas take away from the tutorial. @smythp may be able to come up with a better idea for improving the focus.

mkudzia commented 6 years ago

Thanks @greebie -- obviously I thought yours was good too!

I agree that ultimately the matter at hand is fine-tuning the focus of the existing tutorial. I think I might have wandered afield from that point so it would be good for me to re-emphasize that here. @smythp I'm excited to see what you ultimately decide to do.

walshbr commented 6 years ago

Thanks for the helpful reviews, both! @smythp - feel free to ask for any clarification or open things up if there is anything you'd like to discuss. For my own part, it seems like the consistent thing from the reviewers is a concern for the audience the tutorial pitches itself towards. I'll confess that my own concern is always for the novice reader. It also is totally reasonable to pitch it for a different audience, though, so long as you are clear about the audience up front and in the learning outcomes. And if you do decide that you wanted to try to peel off part of this lesson for another tutorial I can always take that conversation back to the board. I'm happy to offer any further thoughts you might want @smythp.

And as a reminder, we ask that any revisions be completed in four weeks. Delay is fine - just keep me in the loop. So just let me know whenever you feel satisfied that you can start working so that I can put a reminder to get in touch in my own calendar. And feel free to get in touch if you have questions as you're going.

smythp commented 6 years ago

Two of the questions you raised were concerns of mine when writing the tutorial. One, that it was too long, and so would put off new people, and two, that it's a large, diverse, and relatively tough domain, which is also, I think, why there are no REST API tutorials on Programming Historian currently and why those that exist on the internet at large generally aren't beginner-friendly. In tackling APIs here, I made some compromises in the direction of comprehensibility and scaffolding that I think make this tutorial a little unusual and, to be frank, slightly unwieldy. With that said, though, I think these compromises allowed me to tackle a topic that's useful to PI readers, especially librarians and the text analysis DH crowd. I think that this lesson could likely be split up into a series, but my feeling is that the admittedly somewhat monolithic nature of this tutorial lets it do some work and target a somewhat different audience than a series would, and also lets me introduce these concepts in a more gentle way than would otherwise be possible.

As you say, APIs can be pretty abstract unless you're already approaching them from the perspective of a programmer who has worked with them already. In the original version of this tutorial, I didn't include the Chronicling America example at all. It does indeed venture into the field of using APIs, not creating them, and learning to use an API isn't really the goal of this tutorial. However, without that use case, it was hard to scaffold for the reader in a concrete way some of the concepts they needed to really understand the later sections. Stuff like how a user accesses APIs in practice, the anatomy of a request/URI, and some other items were just too dry and abstract without this more concrete example. So while I agree it's off the beaten path here, it's the best, though admittedly imperfect, solution I could come up with for concretizing what an API is and does before getting into the weeds.

So I guess what I'm saying is that I think it makes more sense to keep the tutorial together. Splitting it up would make the length much less intimidating, but the Chronicling America example was created more as scaffolding, and though I agree that it might be able to stand on its own it seems that without it, readers might have a harder time with the later sections.

@greebie and @mkudzia, you're right that framing the tutorial for complete beginners, i.e. non-programmers, might be unrealistic. The comment about dictionaries makes a lot of sense to me, there's just too much going on in the code for those who have never used an editor, the cli, or Python to manage it all cognitively. Reframing it for people with some background in Python will also let me tighten up the prose in some sections, though in general I like to provide too much explanation than too little. Looking at the tutorial again, I think many sections do seem to read like they assume a beginning programmer, but I don't frame it that way in the introduction.

I agree with the other feedback, including tightening up the tutorial by removing some sections and reorganizing others. I may keep the chart but will add a sentence or two to frame it better and give an idea of its provenance.

For the Hugo example, I had a data set provided by another researcher with text files of all Hugo novel award winners. I mostly just used Emacs macros to grab the first lines, did a little hand cleaning, and wrote a Python script to create an SQLite database. So kind of automated, kind of by hand.

I didn't think to write more about virtual environments and version hell. It's a pretty messy area and people seem to have a lot of ways of dealing with it, from sticking to Anaconda and the conda command to (as you alluded) using binaries called python3 and pip3 to writing scripts to mess around with the path. I personally use a utility called pyenv which I'm very satisfied with. It's a command line utility that lets you switch among Python 3, Python 2, and Anaconda, and I think some other implementations. You can switch globally or within a project folder. I don't think it works on Windows but on Mac or Linux it's great. https://github.com/pyenv/pyenv

In any case, to sum up: I'm open to pushback about splitting this into two or even three separate tutorials, but my instinct as a teacher is to keep it together but to target a beginner to intermediate audience. I think the presence of the Chronicling America example as scaffolding is preferable, even if it's a little off the beaten path. I'll link to more Python resources at the beginning and change the prerequisites. I'll also implement the great line-by-line advice for tightening up the tutorial.

Please let me know what you think about this plan, and thanks for your reviews and for the excellent feedback!

walshbr commented 6 years ago

Splitting things off also makes it less likely that a second or third tutorial will be finished - life gets in the way, even with all the best intentions. Certainly not the only consideration, though, and the advice to resist the urge to be all things to all people to all people is a good one. I think your reasoning here makes a lot of sense @smythp. A lot of this might have to do with framing, both in a global sense and then in the individual sections. A sentence here and there to further stitches things together and makes clear why you have the particular sections you have can go a long way. A lot of times things that seem out of scope in a writing piece can be brought back with care and attention to the logic and reading of the thing, and it seems like @mkudzia and @greebie have pointed out those places to focus on if you're committed to keeping those pieces.

For example, it could potentially also be a question of framing for the design principles section. Ie - rather than saying "this is an aside before we go further," you could frame it as "let's take a moment to examine the decisions that we've already made and why they're important." That's basically what is happening now, as I read it, so might just be a matter of framing the way you get into and out of the section to better reflect that. And then tightening up the example moments in the principles section so that they're more clearly reflecting on what the user has already been doing rather than hypotheticals. A sentence here and there to that effect could help that.

As for Python versions - I think we have many solutions to solving this problem, even in the PH lessons. It agree that it's worth erring on the side of offering advice for people as to where they can run into problems if you're not going to go into detail about potential issues. If there does seem to be one potential problem that people are more likely to run into, that could be worth mentioning. But otherwise I think it's fine to point people elsewhere.

walshbr commented 6 years ago

Ah and @smythp this is a bit of a sneak preview, but we're working to make sustainability more of a consistent conversation at PH. We have a preview of our upcoming sustainability guidelines available here - https://deploy-preview-612--ph-dev.netlify.com/lesson-retirement-policy#related-sustainability-guidelines. You might glance at them to see if they give you any thoughts as you're revising. Some of it is relevant to the current discussion we're having about Python versions, for example.

smythp commented 6 years ago

Thank you, Brandon. Over the next few weeks I'll consider the excellent advice here and use it to tighten up the lesson, with special consideration to audience. Thanks again, all!

More consideration for sustainability is a great idea, both for PH and as a wider concern in DH in general. I actually also had an accessibility concern with images that I wanted to run by you, but I'll send you the details out of band.

I'll check in in a few weeks! Looking forward to sharing a final version.

walshbr commented 6 years ago

Sounds good! I'm happy to discuss by email, but if you had thoughts about something that is not mentioned in the sustainability guidelines they're probably worth mentioning on those tickets on the main repo as well #534 for sustainability more generally and #612 for the pull request that is gathering all those materials for discussion and preview. Feel free to jump into one of those conversations if you're so inclined. The pull request, especially, we've been circulating for the broader community/public to take part in discussion.

walshbr commented 6 years ago

@smythp - just wanted to check in since it's been about a month. How are you feeling about timeline for revision here? No worries if you've been delayed.

smythp commented 6 years ago

Just under a bit of a writing crunch at the moment. Doing final edits just after the holidays would be ideal, but can get to it earlier if you think it's warranted. Sorry for not checking in!

walshbr commented 6 years ago

That sounds good to me! I'll make a note to get back in touch if I don't hear from you.

walshbr commented 6 years ago

Just a note on timeline - @smythp and I have been talking behind the scenes and set March 20th as a tentative date for revisions to come in.

smythp commented 6 years ago

Below are my notes for the final revisions for this article. I forgot to reference this issue in my commit message, here's the link to the commit:

https://github.com/programminghistorian/ph-submissions/commit/0bd5b2476c32cdb5055de1cf515940234a2ed1d7

Sorry if my notes below are a little verbose, I kept track as I made changes in case it would be helpful in the final review.

I think the tutorial is considerably stronger after incorporating the feedback from your reviews and our discussions. Looking forward to next steps!

walshbr commented 6 years ago

Thanks @smythp! I'll take a look at this later in the week and get back to you asap.

walshbr commented 6 years ago

@smythp - this looks great. I think you did a good job of addressing the concerns from the reviewers. I just went through and did a copy editing read and tried to think of any other things that might come up. Below are the results of that read. They are very minor requests, and hopefully they shouldn't take very long. Once you have a chance to commit the few sentences and tweaks I'll go ahead and take the steps necessary to publish!

smythp commented 6 years ago

Hi Brandon,

I've pushed a commit with the new, possibly final, version. The GET/POST parentheticals were written from the perspective of the app/server rather than the client or browser, but I agree that that could be confusing. I've added a little clarifying language to that section. I've pushed the database to the assets folder and updated the link so it works in my local Jekyll server, but not sure if it working in ph-submissions translates to it working on the live site, so any clarity on that would be appreciated. I've removed the Marvel API, which is a good API but perhaps not hitting the right note, and added the World Bank API and Europeana Pro. I think the examples have more of a global tenor now, the only somewhat parochial one is NYPL. Let me know if you think the World Bank is problematic at all.

Thanks again, and let me know if other changes are needed.

Best, Patrick

walshbr commented 6 years ago

Thanks @smythp. Consider us soft launched! 🎉 I've done all the steps up to including you in the Twitter bot workflow and/or advertising broadly.

I've opened a pull request on the main repository if you want to take a look. I found one syntax issue that was causing some weird code highlighting, and we use an include for the table of contents, so I got rid of yours and threw ours in. You can see the preview here - https://deploy-preview-773--ph-dev.netlify.com/lessons/creating-apis-with-python-and-flask. If you'd prefer to comment on the PR directly you can do so here - https://github.com/programminghistorian/jekyll/pull/773.

Also check out the short 1-2 sentence bio that I gave you at the bottom of the page as well as the abstract at the top. I can modify them in any way you want if you just let me know what you want there.

Take a look and see if you notice any issues? Once I get your once over I'll finalize.

smythp commented 6 years ago

Hi Brandon,

It's looking great! Thank you for all your hard work on this, I'm excited to see it finished!

Might I use this description and one-sentence bio?

Learn how to set up a basic Application Programming Interface (API) to make your data more accessible to users. Discussion of principles of API design and the benefits of APIs for digital projects.

Patrick Smyth is a PhD student in English and Digital Fellow at the Graduate Center, CUNY.

Thanks again, and let me know if I need to do anything else. Give me a heads-up when it goes up so I can share on Twitter. :)

Best, Patrick

walshbr commented 6 years ago

Yep! For the abstract, how about:

Learn how to set up a basic Application Programming Interface (API) to make your data more accessible to users. This lesson also discusses principles of API design and the benefits of APIs for digital projects.

That way they're both full sentences - feel free to tweak. Will add those once you confirm. I'll ping you on Twitter for sure. Thanks for your hard work. I'll finalize ASAP, close this when done, and then publicize. I'll let you know if anything else comes up.

smythp commented 6 years ago

Looks good to me! Thanks again, Brandon.

greebie commented 6 years ago

Sorry for not engaging this too much after the fact (too many github notifications to follow), but congratulations @smythp on the progress to your paper! Look forward to seeing it on the main site.

smythp commented 6 years ago

Thank you, Ryan, for your review. It was much appreciated. A big thank you to Megan as well!

smythp commented 6 years ago

Sorry for the last minute spot check, but I noticed there's a typo in one of my headings:

AN API Case Study: Sensationalism and Historical Fires The N in "An" shouldn't be capitalized.

walshbr commented 6 years ago

No worries @smythp - definitely keep spot checking. I'll glance through again before publishing as well.

walshbr commented 6 years ago

We're live - https://programminghistorian.org/lessons/creating-apis-with-python-and-flask! I'll tweet out on social media tomorrow for maximum outreach (rather than doing it at the end of the work day EST). Be on the lookout, and please promote it, retweet it, etc. Thanks for all of your work @smythp @mkudzia @greebie - really great working with you! And let me know if you find any issues in the lesson.

mkudzia commented 6 years ago

Huzzah! Great work @smythp -- so exciting to see it live!

svmelton commented 4 years ago

Just passing along a compliment from a reader that arrived in my inbox: "[the tutorial is] well written, it helped me export my first Python API flawlessly... At a time when I'm struggling to learn all sorts of new things, such small successes go a long way in keeping me motivated."

Good work, @smythp!

smythp commented 4 years ago

Thank you! I actually receive a decent amount of email about the tutorial from those who have found it helpful, most of whom seem to be outside the world of DH. I also talk up the PH editorial process when I have the opportunity, as the collaboration was key to making a strong lesson. The article seems to have some legs in the community, and I'm grateful for that. Perhaps I'll have to write another one once I finally turn in my dissertation.

greebie commented 4 years ago

Always nice to hear that I contributed to something that people use. Congrats @smythp @mkudzia!

smythp commented 4 years ago

Yes, thanks to @walshbr, @mkudzia, and @greebie. You just need to scroll up to see all the hard work that went into this! Wish all publishing processes were like PH's.