Package: basecampapi
Basecamp APIThis package allows simple interaction withBasecamp APIusing Python.Table of contentsInstallationInitial authentication: Getting your refresh tokenAuthentication with Refresh tokenAttachmentsAdditional information1. InstallationThe package can be installed from your terminal by typing:pip install basecampapiYou need to have python 3.7 or higher installed.2. Initial authentication: Getting your refresh tokenYou only need to do this the first time. Once you get your Refresh token you should pass it with your credentials to gain access.If you already have a Refresh token you should skip this step.To be able to interact with Basecamp's API, we need to provide an access token upon each API request. Basecamp's access tokens are set to expire 2 weeks after being generated, which is why we need to generate a refresh token.Refresh token allows us to automate the process of generating an access token. We only have to generate the refresh token once and after that we can use it to gain access to Basecamp each time we run our script.To gain access you need a developer app on Basecamp. App can be created onhttps://launchpad.37signals.com/integrations, after which you need to use the generated Client ID, Client Secret and the Redirect URI which you provided for initial authentication. You can read more about the authentication process onBasecamp API Authenticationpage.To begin the authentication process, you need to create a dictionary with your app credentials and use it in theBasecampobject:frombasecampapiimportBasecampyour_credentials={"account_id":"your-account-id","client_id":"your-client-id","client_secret":"your-client-secret","redirect_uri":"your-redirect-uri"}bc=Basecamp(credentials=your_credentials)Your account ID can be found on your Basecamp home page, in the URL address:https://3.basecamp.com/YOUR-ACCOUNT-ID/projectsIf your credentials dictionary does not contain a "refresh_token", an error will be raised which contains a link for the authorization of your app. You need to open that link on the browser where you are logged into your Basecamp account and  click on "Yes, I'll allow access":Clicking that button will redirect you to the link you provided as Redirect URI in your credentials, but it will have the verification code in the url address. Save that verification code:Initiate theBasecampobject again, and provide the code you gathered via theverification_codeparameter:# Verification code variableyour_verification_code="17beb4cd"bc=Basecamp(credentials=your_credentials,verification_code=your_verification_code)This will generate your Refresh token and use that token right away to generate the Access token for your current session. You need to generate your Refresh token only once, but that Refresh token will be used to generate Access token each time you initialize theBasecampobject.3. Authentication with Refresh tokenTo interact with objects on Basecamp you have to initialize theBasecamoobject. This object will generate your access token and allow you to interact with other Basecamp objects.frombasecampapiimportBasecampyour_credentials={"account_id":"your-account-id","client_id":"your-client-id","client_secret":"your-client-secret","redirect_uri":"your-redirect-uri","refresh_token":"your-refresh-token"}bc=Basecamp(credentials=your_credentials)This generates the Access token which is then used in object that interact with Basecamp.frombasecampapiimportCampfire# Initiates a Campfire object using previously created sessionyour_campfire=Campfire(campfire_id='your-campfire-id',project_id='your-project-id')# Sends a campfire message with desired contentyour_campfire.write(content="Hello from Python!")4. AttachmentsWhen attaching images or other files to Basecamp posts we do this by usingRich text, which means that we will be sending HTML as content to the Basecamp object we want to interact with.Sending rich text through API is not allowed on all Basecamp objects that have rich text by themselves. Best example are Campfires, when interacting with Basecamp you can upload images and files to a campfire or edit the text style, but Basecamp API does not allow this to be done programatically. Here is alistof Basecamp endpoints that can accept rich text.To upload a file to Basecamp, first we need upload the file to Basecamp's server and get itsattachable_sgid. You can do this by using theAttachmentsobject and itsupload_file()method:frombasecampapiimportAttachmentsmy_att=Attachments()my_att.upload_file("folder/image.png",filename="my_image")After this the file will be on Basecamp's server and it will have an automatically generatedattachable_sgidUploaded files can be accessed throughAttachments.filesdictionary:print(my_att.files)This returns a dictionary of dictionaries which contain information about the files you uploaded:{"my_image":{'filename':'my_image','file_size':'155291','content-type':'image/png','sgid':'your-file-sgid'}}To attach a file inside a Basecamp post, comment or any other object where rich text is accessible through API, we need to send an HTML string  as the content parameter of the object we are interacting with, and we need to use the<bc-attachment>tag for any file attachments."<bc-attachment sgid='your-file-sgid'></bc-attachment>"Creating a new Message Board post on Basecamp with our uploaded image will look like this:frombasecampapiimportMessageBoard# Constructing the content stringcontent="Hello world! <br> \<bc-attachmentsgid='#######'caption='My image'></bc-attachment><br>\Thisisanimagesentfrompython."# Initiating the message board objectmessage_board=MessageBoard(project_id=123456,message_board_id=123456)# Creating a messagemessage_board.create_message(subject="Test message",content=content)5. Additional informationCurrently available endpoints:Campfire - allows reading campfire messages and writing to campfiresMessageBoard - allows reading, creating and updating messages, as well as reading, creating and updating comments on messagesAttachments - used for uploading files and attaching them to with other Basecamp objectsFuture upgrades:Vaults (Docs & Files)To-dosRequest new features inissues.